Penguin Orchestration

Penguin Orchestration

The penguin CLI is a thin client of the PenguinHarness server. Inside a harness agent session it reaches the same server that is running you, so you can orchestrate the platform yourself: list and create agents, start conversations with them, steer those conversations while they run, and query costs and scheduled tasks.

Before you start

If the user's message only invokes this skill (e.g. "use penguin-orchestration skill") without a concrete request, ask the user what they want to orchestrate. Read-only commands (project ls, agent ls, ls, logs, cost, schedule ls) are always safe; do not create agents, start sessions or send messages until the goal is clear.

How the connection works

• Inside a harness agent session (you, now): every command subprocess has PENGUIN_API_URL, PENGUIN_API_TOKEN, PENGUIN_PROJECT_ID, PENGUIN_AGENT_ID and PENGUIN_SESSION_ID injected, so penguin commands automatically reach your own server with your project and agent as the defaults — no login step.
• Outside an agent (a human shell): the CLI attaches to the running local server via its lock file, or auto-starts one; the local <data-root>/api-token file (0600) authenticates it.
• You are operating the same server that runs you: sessions and agents you create appear live in the web UI, where the user sees and owns everything you spawn.
• The injected token is admin-equivalent. Act accordingly: stick to what the task requires, and prefer read-only commands until a mutation is clearly needed.

Orient first

Before mutating anything, see what exists:

penguin project ls        # projects on this server
penguin agent ls          # agents in the current project
penguin ls --json         # the project's sessions, with running state

--json on any listing gives machine-parseable output.

Command surface

penguin run -m <msg> [--project-id <id>] [--agent-id <id>] [--workspace <path>]
            [--model-id <id> --provider <p>] [--approve <mode>] [--thinking <level>]
            [--session <session_id>] [--background] [--timeout <duration>]
            [--goal [budget]] [--json]
penguin ls [--project-id <id>] [--agent-id <id>] [--days <n>] [-a|--all] [--json]
penguin input [session_id] [-m <text>] [--timeout <duration>]
              [--project-id <id>] [--agent-id <id>] [--json] [--server <url>]
penguin logs [session_id] [--project-id <id>] [--agent-id <id>] [--tail <n>]
             [-f|--follow] [--timeout <duration>] [--json]
penguin agent ls [--project-id <id>] [--json]
penguin agent create --agent-id <id> [--name <s>] [--description <s>] [--skills <a,b>]
                     [--project-id <id>] [--json]
penguin project ls [--json]
penguin cost [--days <n>] [--from <d> --to <d>] [--by date|agent|model|session]
             [--project-id <id>] [--agent-id <id>] [--json]
penguin schedule ls [--project-id <id>] [--agent-id <id>] [--json]
penguin schedule add <name> --prompt <s> --start-at <ISO|now> [--period <duration>]
                    [--end-at <ISO>] [--session-id <id> | --workspace <path>
                    [--model-id <id> --provider <p>]] [--disabled]
                    [--project-id <id>] [--agent-id <id>]
penguin schedule update <name> [<same field flags>] [--enable|--disable]
                    [--project-id <id>] [--agent-id <id>]
penguin schedule rm <name> [--project-id <id>] [--agent-id <id>]

• run starts a task and waits, rendering the conversation, unless --background — then it prints the new session id and exits while the server keeps running the task. --session <session_id> runs the task in an existing session instead of creating one; the model reference is the --provider + --model-id pair (both or neither); --goal [budget] runs in goal mode — the session loops until the agent declares the goal complete, with an optional spend budget.
• Caller-context defaults. Inside a harness agent, a session-creating run fills every field you leave unspecified from your own live session, per field independently: --workspace, the --model-id/--provider pair, --approve and --thinking inherit the caller's values — the same convention as run_subagent parent inheritance. Precedence: explicit flag > caller value > plain fallback (cwd, the Project default model, allow-all, none — used wholesale if the caller lookup fails, with a dim stderr note). So inside an agent, penguin run -m "..." alone typically does the right thing; pass flags only to diverge.
• --timeout <duration> (30s, 5m, 2h, or bare seconds) bounds the wait of a foreground run, an input, or a logs -f. Expiry is a soft yield, not an error: the command exits 0 while the task keeps running server-side, printing a still-running note that names the follow-up commands (--json prints {sessionId, status: "running", text} with the text so far). --timeout 0 (also 0s) returns immediately after delivery — the same note without collected text (--json: {sessionId, status: "running"}); on a bare poll it snapshots a running session instantly. run --background stays the idiomatic fire-and-forget for new tasks and rejects --timeout; logs --timeout requires -f.
• input with -m steers a running session mid-turn (the agent absorbs it as a course correction within the current task) or starts a new turn on an idle one; it waits for the reply unless a --timeout bounds the wait (--timeout 0 = deliver and return at once). Bare input [session_id] (no -m) polls: it prints the session's most recent complete assistant text — an idempotent snapshot that skips user/thinking/tool output and never touches approvals, mirroring input_subagent's empty-prompt semantics. A running session is waited on first (bounded by --timeout, else indefinitely); a session with no reply yet prints (no assistant reply yet). --json reports {sessionId, status, text} — idle/running when polling, completed/aborted/running with -m.
• ls spans every agent of the project, newest first (by last active); archived sessions are left out unless -a/--all includes them, and --days <n> keeps only sessions last active since local midnight n−1 days ago — today counts as day 1, so --days 2 is yesterday and today, --days 7 this week. logs renders a session's transcript: --tail <n> for the last entries, -f to follow live.
• Session ids embed their creation timestamp — session-YYYY-MM-DD-HH-mm-ss-<8hex>. Every <session_id> argument takes any unique substring of an id; the 8-hex tail is the recommended short form, and an ambiguous fragment errors listing the candidates. On input and logs, --project-id scopes that fragment search (unnecessary with a full id).
• On input and logs the id is optional altogether: omitted, it is the agent's most recent session, off the same newest-first listing chat --resume uses, with --agent-id picking whose. The chosen id is announced as a dim [latest] line on stderr, so the target is never ambiguous and --json on stdout stays parseable. Bare penguin logs is therefore "what just happened" and bare penguin input is "what did my agent last say"; an agent with no session at all gets one line pointing at penguin run and a non-zero exit.

Recipes

Yesterday's or this week's sessions, with their latest replies

penguin ls --days 2 --json    # yesterday + today (today counts as day 1)
penguin ls --days 7 --json    # this week; add -a to include archived sessions
penguin input <session_id>    # one session's latest complete assistant reply

• --days <n> keeps sessions last active since local midnight n−1 days ago. For strictly-yesterday, take --days 2 and drop today's entries client-side — ids embed the creation date and the JSON carries last-active.
• Bare input prints the latest reply; add --timeout 0 to snapshot a running session instantly instead of waiting for its turn to finish.

Summarize this week's history in a new session

A fresh session gets a fresh context window for the summary; feed it through a file, not the prompt:

penguin ls --days 7 --json               # pick the sessions
penguin logs <session_id> --tail 100     # gather each transcript (widen if cut short)
# write what you gathered into a workspace file with your file tools, then:
penguin run -m "Read ./weekly-material.md and write the weekly summary to ./weekly-summary.md"

• Exchange big material through workspace files. Caller-context defaults mean the new session shares your workspace — write the gathered transcripts to ./weekly-material.md and have the new session read it there. Pages of transcript do not belong in -m.
• Read the result from ./weekly-summary.md (the foreground run also renders the reply).

Create an agent and say hello

penguin agent create --agent-id greeter --name "Greeter" --description "Welcomes people"
penguin run --agent-id greeter -m "Hello! Introduce yourself."

• Agent ids must match ^[a-z][a-z0-9_]{1,63}$: a lowercase letter first, then lowercase letters, digits and underscores — no hyphens.
• A newly created agent starts with no skills preinstalled: seed it at creation with --skills a,b (library names) — include penguin-orchestration itself when the new agent must drive the harness too.
• --agent-id switches only the agent: workspace, model, approval and thinking still inherit from your own session (caller-context defaults) — add those flags to change them too. Each run without --session opens a fresh session; reuse a session id to continue a conversation.

Summarize each agent's costs in a new session

penguin cost --days 7 --by agent --json    # who spent what this week
penguin run -m "Summarize this per-agent cost report and flag anomalies: <the JSON>"

• The default penguin cost card already carries today / last 7 days / total; --by date|model|session and --from <d> --to <d> give the other cuts, --project-id / --agent-id narrow the scope.
• A --by agent report is small enough to inline in -m; for long breakdowns (--by session over a busy week), use the file-exchange pattern from the weekly-summary recipe.