CLI Reference¶

The aigo CLI tool provides command-line access to the Backend.AI GO Management API. Use this tool to manage local models, control inference servers, monitor system resources, and interact with loaded models from the terminal.

Installation¶

The CLI is included with the Backend.AI GO distribution. If you are building from source:

cd cli
cargo install --path .

Usage¶

aigo [OPTIONS] <COMMAND>

Auto-Discovery¶

When --endpoint is not specified, the CLI automatically discovers a running Backend.AI GO instance by reading a discovery file written by the Management API server at startup. No configuration is required for the most common case of connecting to a locally running instance.

Endpoint resolution order:

1. --endpoint flag or BACKEND_AI_GO_ENDPOINT environment variable (explicit override)
2. Config file endpoint (if changed from the default via aigo config set endpoint ...)
3. Auto-discovery file (if a local instance is running and healthy)
4. Default fallback: http://127.0.0.1:8001

Discovery file locations by OS:

• macOS: ~/Library/Application Support/ai.backend.go/mgmt-api.json
• Linux: $XDG_RUNTIME_DIR/ai.backend.go/mgmt-api.json (fallback: ~/.config/ai.backend.go/mgmt-api.json)
• Windows: %APPDATA%\ai.backend.go\mgmt-api.json

Before connecting, the CLI validates the discovery file by checking that the server process (identified by PID) is still running and that the endpoint responds to a health check. Stale files from crashed instances are silently ignored.

Top-level command index¶

The CLI has many top-level commands. The table below is generated from cli/src/commands/mod.rs and is the authoritative index of the current command groups.

For exact flags and nested subcommands, always use aigo <command> --help and, when needed, aigo <command> <subcommand> --help. The prose below keeps detailed examples for commonly used flows, but it is not a full flag dump.

Global Options¶

Commands¶

chat - One-Shot Chat Completion¶

Send a single message to a loaded model and print the response.

aigo chat [OPTIONS] [MESSAGE]

If MESSAGE is omitted, input is read from stdin (up to 1 MiB).

Options:

When --reasoning-effort is set to a level other than none, the request sends both reasoning_effort and chat_template_kwargs: {"enable_thinking": true}. When set to none, or when --no-think is passed, only chat_template_kwargs: {"enable_thinking": false} is sent, which is the correct way to suppress the <think> block on Qwen3/3.5 hybrid-thinking models.

--thinking-budget and --preserve-thinking are independent of --reasoning-effort: the budget caps how many tokens the model can emit inside <think>, and preserve_thinking controls whether prior <think> blocks survive in the prompt. Both fields travel in the per-request HTTP body, so they are forwarded unchanged to llama-server and mlxcel-server (and through the continuum-router passthrough path).

Examples:

# Basic chat
aigo chat "What is the capital of France?"

# Disable thinking mode on a Qwen3 model
aigo chat --no-think "Summarize this document" < report.txt

# Enable thinking with medium effort
aigo chat --reasoning-effort medium "Solve this step by step: ..."

# Cap thinking at 64 tokens (force concise reasoning)
aigo chat --thinking-budget 64 --reasoning-effort high "Quick: 2+2=?"

# Disable thinking via the budget (equivalent to --no-think for engines that implement it)
aigo chat --thinking-budget 0 "Just answer directly."

# Preserve <think> blocks across turns on Qwen3.6+ (improves agent KV cache reuse)
aigo chat --preserve-thinking --reasoning-effort high "Continue solving from where we left off."

# Pipe input with a system prompt
echo "SELECT * FROM users" | aigo chat --system "You are a SQL expert."

complete - One-Shot Text Completion¶

Send a prompt for text completion (non-chat format).

aigo complete [OPTIONS] [PROMPT]

If PROMPT is omitted, input is read from stdin.

Options:

config - Configuration Management¶

Manage CLI configuration settings.

• aigo config path: Show configuration file path.
• aigo config get <KEY>: Get a configuration value.
• aigo config set <KEY> <VALUE>: Set a configuration value.
• aigo config list: List all configuration values.
• aigo config reset: Reset configuration to defaults.

model - Local Model Management¶

Manage models stored on the local disk.

• aigo model list: List all local models.
• aigo model info <MODEL_ID>: Get detailed information about a specific model.
• aigo model refresh: Refresh the model index (scan for new files).

loaded - Loaded Model Operations¶

Control models currently loaded into memory for inference.

• aigo loaded list: List currently loaded models.
• aigo loaded info <ID>: Get details of a loaded model instance.
• aigo loaded load [OPTIONS] <MODEL_ID>: Load a model into memory.
  • Options:
    • -c, --context-length <INT>: Override context length.
    • -g, --gpu-layers <INT>: Number of layers to offload to GPU (-1 for all).
    • -t, --threads <INT>: Number of threads to use.
    • -a, --alias <STRING>: Model alias for routing.
    • --tool-calling: Enable tool calling capabilities.
    • --mmproj <PATH>: Path to mmproj file for vision models.
• aigo loaded unload <ID>: Unload a model to free resources.
• aigo loaded health <ID>: Check the health status of a loaded model.

router - Router Control¶

Manage the Continuum Router service.

• aigo router status: Get the current status of the router.
• aigo router start: Start the router service.
• aigo router stop: Stop the router service.
• aigo router restart: Restart the router service.
• aigo router verify-endpoint --json <BODY>: Probe an Anthropic-compatible endpoint. The body (--json or --file) carries baseUrl, apiKey, and model; the API key is sent in the request only and never echoed.

system - System Monitoring¶

Monitor hardware resources and API status.

• aigo system info: Get general system information (OS, Architecture).
• aigo system metrics: Get current system metrics (CPU, RAM usage).
• aigo system gpu: Get detailed GPU information.
• aigo system health: Check the overall API health.
• aigo system version: Get the API server version.

extension - Extension Skills and Imports¶

Manage Claude Code / Codex skills and import subagent / AGENTS.md definitions. Commands with complex bodies accept --json <STRING> or --file <PATH>.

• aigo extension skill list: List installed skills.
• aigo extension skill show <ID>: Show a skill.
• aigo extension skill create --json <BODY>: Create a skill (ExtensionSkill shape).
• aigo extension skill update <ID> --json <BODY>: Update a skill.
• aigo extension skill delete <ID> [-y]: Delete a skill.
• aigo extension skill enable <ID> / disable <ID>: Toggle a skill.
• aigo extension skill invoke <ID> [--json <BODY>]: Render a skill for invocation (body defaults to {}).
• aigo extension skill import-file <PATH>: Import a skill from a server-side file path.
• aigo extension skill import-url <URL>: Import a skill from an https:// URL.
• aigo extension skill parse --json <BODY>: Parse skill content (content/sourceHint).
• aigo extension skill activation-preview --json <BODY>: Preview permission mapping for skill content.
• aigo extension skill fork preview --json <BODY> / fork run --json <BODY>: Preview or run a context: fork skill.
• aigo extension agent parse --json <BODY> / agent import --json <BODY>: Preview or import a subagent / AGENTS.md as an agent profile.
• aigo extension discover: Discover importable Claude Code / Codex artifacts on disk.

events - Live Event Streams¶

Follow the Management API event bus from a script. aigo events carries the whole bus and needs the admin scope; the per-domain watchers below need only their own domain's read scope, so a key that can read the Data Hub can watch it without being able to watch anything else.

Two transports carry the same events, so a command can switch between them without re-parsing anything. SSE (--transport sse) is an ordinary GET: it needs no upgrade, works through a TLS endpoint, and works over the Unix socket. The WebSocket (--transport ws) adds an opening stream:ready frame carrying a safe resume anchor, which is what lets a client reconnect without skipping a backlog or losing the interval before its first product event. It is the default where losing a run's outcome would matter. The socket has no TLS support here, so an https:// endpoint falls back to SSE.

• aigo events [--types <A,B>] [--since <ID>] [--transport sse|ws] [--raw]: Follow every event on the bus. Console output is one line per event, HH:MM:SS.mmm <type> <summary>; --raw, -o json and -o yaml print one JSON object per line instead. Ctrl-C exits 0.
• aigo squad events [<SQUAD_ID>] [OPTIONS]: One squad's events with an id, every squad's and every discussion room's without one. Both forms support SSE and WebSocket.
• aigo schedule events [OPTIONS]: The schedule:* lifecycle family, as automation runs start, finish, and fail.
• aigo memory events [OPTIONS]: The memory:* family.
• aigo data events [OPTIONS]: The data:* family, including the ingest, folder-import, and embedding progress the --follow modes ride.

--types names event types exactly and the server validates them: a name outside the route's domain is refused with a 400 rather than accepted into a stream that connects and then delivers nothing. --since <ID> resumes from an event id, delivering whatever the server still holds in its replay buffer first. A resume point that fell out of that buffer produces a stream:gap event and a client that falls behind produces stream:lagged; neither is removed by --types, because a client that asked for one event type still has to hear that it lost events.

A dropped connection is re-subscribed from the latest safe cursor, backing off 1, 2, 4, 8 and 16 seconds and giving up after five attempts. This is normally the highest product-event id received, or a fresh WebSocket's opening anchor before the first product event. After a server restart, stream:gap causes the first replayed event in the new id epoch to replace the stale cursor. Each reconnection prints a line to standard error naming the resume point.

The follow modes elsewhere in this reference ride the same streams: aigo squad execute --follow, aigo squad execution --follow, aigo squad message --wait, aigo squad discussion watch, and the three aigo data ... --follow waits.

A server built before these endpoints existed answers them with 404. aigo events and the per-domain watchers report that as an error naming the version that serves them, because there is nothing else for them to do. The --follow modes fall back to their earlier polling behaviour and say so on standard error, so --follow keeps working against an older server. A 401 or a 403 is a real failure and is never answered by quietly polling instead.

aigo events --types squad:task-completed,data:ingest-progress
aigo squad events sq-1 --transport ws --raw | jq -r 'select(.type == "squad:task-failed") | .payload.error'

schedule - Automations (Scheduled Tasks)¶

Create and manage automations: cron-driven inference runs, called Automations in the desktop UI and schedules in the Management API. create and update take typed flags; --json <BODY> and --file <PATH> carry a full request body instead, and --file - reads it from stdin. The 1 MiB cap applies to --file and to stdin; an inline --json body is bounded only by the shell's argument limit.

The cron expression is validated before the request is sent, so a bad expression is rejected with the server's own reason instead of a 4xx.

The endpoints behind these commands, the wire shape of a schedule and an execution, and the cron and timezone rules are in the Automations API reference.

• aigo schedule list: List automations (ID, name, cron, timezone, model, enabled, next run, last run).
• aigo schedule show <ID>: Show one automation in full, including the prompt template and system prompt.
• aigo schedule create --name <NAME> --cron <EXPR> --model <MODEL> (--prompt <TEMPLATE> | --prompt-file <PATH>) [OPTIONS]: Create an automation. The four named flags are required because the server's CreateScheduleRequest has no default for them.
• aigo schedule update <ID> [OPTIONS]: Update an automation. Only the flags given are sent; an invocation with no flag at all is an argument error.
• aigo schedule delete <ID> [-y]: Delete an automation and its execution history.
• aigo schedule toggle <ID>: Flip an automation between enabled and disabled.
• aigo schedule run <ID> [--no-wait]: Run an automation immediately and print the execution record. The call blocks until the run finishes; --no-wait returns as soon as the run is accepted. Under the default console output it prints the execution ID alone, so it pipes into aigo schedule execution show; under -o json or -o yaml it prints the whole {"executionId": ...} object, which a pipeline has to unwrap.
• aigo schedule executions <ID> [--status <STATUS>] [--limit <N>] [--offset <N>]: List the execution history of one automation.
• aigo schedule enable <ID> / aigo schedule disable <ID>: Set the enabled state absolutely. Unlike toggle these are idempotent: running enable twice leaves the automation enabled and exits 0 both times, which is what a provisioning script needs.
• aigo schedule export <ID> [-o <PATH>] / aigo schedule export --all [-o <PATH>]: Write a portable document for one automation or for every one. Without -o the document goes to standard output. Here -o is the destination path, not the global -o/--output format flag; the document is always JSON whatever that format flag says, because it is the input aigo schedule import reads.
• aigo schedule import <PATH> [--on-conflict skip|rename|replace]: Import automations from a document export produced, or from a bare CreateScheduleRequest array. - reads standard input; --json <BODY> passes the document inline. Prints how many were created, skipped, and replaced.
• aigo schedule duplicate <ID> [--name <NAME>]: Copy an automation. The copy is created disabled so it can be edited before it runs, and is named <name> (copy) unless --name is given.
• aigo schedule validate-cron <EXPR>: Validate a cron expression and print its description.
• aigo schedule events [--types <A,B>] [--since <ID>] [--raw]: Follow the schedule:* lifecycle stream, one line per event, until Ctrl-C. See events.

Executions are addressed by their own ID through aigo schedule execution:

• aigo schedule execution list [--schedule <SCHEDULE_ID>] [--status <STATUS>] [--limit <N>] [--offset <N>] (alias ls): List executions across every automation, most recent first.
• aigo schedule execution show <EXECUTION_ID>: Show one execution in full, including the rendered prompt and the whole result.
• aigo schedule execution output <EXECUTION_ID>: Print the execution's result text and nothing else, so it can be piped. A run that did not succeed still prints whatever result it recorded, then writes its status and error to standard error and exits 3, so an empty stdout means the run produced nothing rather than that it failed.
• aigo schedule execution cancel <EXECUTION_ID> [--schedule <SCHEDULE_ID>] [-y]: Cancel a running execution. The owning automation is read off the execution record when --schedule is omitted.

--status takes an execution state: pending, running, success, failed, skipped, or cancelled. Which flags switch the server to its paged response differs between the two listings: on aigo schedule executions <ID> it is --status or --offset, and on aigo schedule execution list it is --status or --schedule, where --offset alone leaves the unpaged array. Once paged, the table footer reads Total: N of M executions, where M counts every execution the filter matched.

That switch also changes the row order on aigo schedule executions <ID>: unfiltered it returns the most recent --limit rows oldest first, which is what it has always done, and any filter returns them most recent first. --limit 0 differs the same way, meaning "no rows" unfiltered and "no ceiling" filtered. Both go away when the paged response becomes the default; until then, pass --offset 0 when you want the newest row first.

aigo schedule execution output exits 3 when the run is anything but success, including a run that has not finished yet. Exit 3 is also what a transport failure reports, so a script that needs to tell the two apart should read the message on standard error rather than the code alone.

aigo schedule execution cancel marks the record cancelled and aborts the inference only in the process that owns the run. A cancel sent to a different process flips the record and is honored at the owner's next write, so the record ends up correct while the model keeps generating until it finishes. Cancelling an execution that has already reached a terminal state is refused. A record left in running by a crashed process is not reconciled at startup, so a running execution older than any plausible run is stale rather than live.

Options shared by create and update:

• --system-prompt <TEXT> / --system-prompt-file <PATH>: System prompt for the inference.
• --agent <AGENT_ID>: Run the automation as an agent profile.
• --input <SPEC>: Where the {{input}} placeholder comes from. One of none, file:<PATH>, dir:<PATH>, url:<URL>, command:<CMD>. Only the first colon separates the two halves, so a URL keeps its scheme.
• --output <SPEC>: What happens to the result. One of store (execution history only), notify (desktop notification), file:<PATH>, webhook:<URL>.
• --tool <NAME>: Enable a tool for the run. Repeatable; repeats of the same name are sent once. On an update the list is replaced wholesale, so name every tool the automation should keep.
• --tool-permission <NAME>=<VALUE>: Per-tool permission override. Repeatable. On an update the stored map is read back first and the named entries are overlaid on it, so other overrides survive; the whole map is replaced only by --clear-tool-permissions.
• --temperature <F>, --max-tokens <N>, --top-p <F>: Sampling parameters. Omitted entirely, the server's defaults (0.7 / 2048 / 0.9) apply. On an update the current values are read back first and only the given ones change, because the server replaces the whole parameter block.
• --timezone <TZ>: IANA timezone for cron evaluation. The server default is UTC.
• --catch-up-missed, --auto-load-model, --unload-after: Run missed executions on startup, load the model before each run, unload it afterwards. On update each also accepts an explicit value (--unload-after false) to turn it off.

Export, import, and duplicate:

• The export document carries only the fields create accepts: no id, no timestamps, no enabled state, and no execution history. That is what makes an import a plain create, and it means an imported automation arrives enabled whatever the source machine had it set to. Disable it with aigo schedule disable <ID> right after importing if that matters.
• An export file is credential material. A webhook: output action holds a URL that is frequently a secret in itself (a Slack or Discord webhook is exactly that), a command: input source holds a shell command line that may embed one, and a url: input source can carry a token in its query string. All three are written verbatim, because an automation stripped of them does not work after an import. The free-text fields carry whatever was put in them, so a key pasted into a prompt or a system prompt travels too, and --model, file:, dir: and saveToFile: paths disclose the source machine's directory layout. Nothing is redacted; treat the file the way you would treat the credentials inside it.
• --on-conflict decides what happens when an incoming name is already taken, and names are the only thing two machines can agree on because an export carries no ids. skip (the default) leaves the stored automation alone and reports the name. rename creates the incoming one as <name> (2), <name> (3), and so on. replace overwrites the stored automation's configuration through the same path an update uses, keeping its id, its enabled state, and its run history.
• A payload is validated whole before anything is written: one bad cron expression refuses the entire import rather than leaving half of it behind. At most 500 automations per request.

Options specific to create:

• --disabled: Disable the automation right after creating it. The server creates every automation enabled, so this is a follow-up toggle call rather than a field on the create body, and it works alongside --json and --file.

Options specific to update:

• --clear-agent, --clear-system-prompt, --clear-tools, --clear-tool-permissions: Send an explicit null for that field, which is the only way to unset it. Omitting a flag leaves the stored value alone.
• --enable / --disable: Set the enabled state after the update is applied. Either one on its own is a valid invocation and sends no update at all.

# A nightly summary of a file, written to another file
aigo schedule create --name nightly --cron "0 2 * * *" --model /models/qwen3-8b.gguf \
  --prompt "Summarize {{input}}" --input file:/tmp/in.txt --output file:/tmp/out.md

# Move it an hour later and drop its agent
aigo schedule update <ID> --cron "0 3 * * *" --clear-agent

# Full request body from stdin, created disabled
echo '{"name":"n","cronExpression":"0 2 * * *","modelPath":"/m.gguf","promptTemplate":"p"}' \
  | aigo schedule create --file - --disabled

# Start a run without waiting, then follow it by ID
EXECUTION=$(aigo schedule run <ID> --no-wait)
aigo schedule execution show "$EXECUTION"

# Recent failures across every automation, then one run's output on its own
aigo schedule execution list --status failed --limit 20
aigo schedule execution output "$EXECUTION" > result.md
# Move every automation to another machine, keeping both copies of any name clash
aigo schedule export --all -o /tmp/automations.json
aigo schedule import /tmp/automations.json --on-conflict rename

# Copy one automation to edit, then turn it on
aigo schedule duplicate <ID> --name staging
aigo schedule enable <NEW_ID>

data - Data Hub Documents¶

Ingest, curate, and search the document corpus behind the desktop Data page. ingest, update, card, summarize and organize take typed flags; --json <BODY> and --file <PATH> carry a full request body instead, and --file - reads it from stdin. The 1 MiB cap applies to --file and to --summary-file / --notes-file; an inline --json body is bounded only by the shell's argument limit. The file ingest reads has its own ceiling, 50 MiB, matching the server's per-file cap rather than the request-body one.

Documents are addressed by their UUID id. The short handle (D42) that list prints is what [[handle]] links inside cards refer to, and show --handle resolves one.

Every command below wraps a Management API endpoint. The endpoint each one calls, its scope, its response shape, and the request fields the server drops rather than rejects are in the Data Hub API reference.

• aigo data document list [--status <STATUS>] [--source <SOURCE>] [--collection <ID>] [--tag <TAG>] [--include-trashed] [--limit <N>] [--offset <N>] (alias ls): List documents (ID, handle, title, kind, status, source, tags, updated). Trashed documents are hidden unless --include-trashed is given.
• aigo data document counts: Print exact lifecycle counts for the corpus, including the non-terminal job count that decides whether trash --all is currently allowed.
• aigo data document show <ID> / aigo data document show --handle <HANDLE>: Show one document in full.
• aigo data document body <ID>: Print the converted Markdown body and nothing else, so it can be piped or redirected.
• aigo data document card <ID>: Print the annotation card. With any write flag it patches the card instead: --summary <TEXT> / --summary-file <PATH>, --key-point <TEXT> (repeatable) / --clear-key-points, --notes <TEXT> / --notes-file <PATH>. --expected-updated-at <RFC3339> refuses the write unless the stored card still carries that timestamp, so a concurrent edit is reported rather than clobbered.
• aigo data document ingest (<PATH> | -) [--title <T>] [--kind <KIND>] [--source <SOURCE>] [--filename <NAME>] [--source-uri <URI>] [--tag <TAG>]... [--collection <ID>]... [--base64]: Ingest a file, or standard input, as a document. --base64 sends the original bytes for a format with no text reading (PDF, DOCX); without it the file is read as UTF-8. --filename defaults to the path's file name and is what the server infers the kind and the original extension from, so an ingest from stdin should set it explicitly or let the server fall back to the frontmatter or first heading for the title.
• aigo data document update <ID> [--title <T>] [--tag <TAG>]... [--clear-tags] [--collection <ID>]... [--clear-collections]: Patch a document's metadata. --tag and --collection replace the whole set, so name every value the document should keep; the --clear-* flags empty it. An invocation with no flag at all is an argument error.
• aigo data document trash [<ID>... | --all | --matching [--status <STATUS>] [--collection <ID>] [--tag <TAG>] [--include-trashed]] [-y]: Soft-delete documents. One id uses DELETE /data/documents/{id}; several go through the bulk endpoint in one transaction, capped at 500 ids. --all trashes every live document, which the server refuses while any ingest, folder import, or watch scan is still running. --matching trashes everything matching the scope filters, resolved on the server at execution time. The three selection kinds are mutually exclusive, and a filter alongside the wrong one is an argument error rather than a silently ignored flag.
• aigo data document restore <ID>...: Restore trashed documents. Only an explicit id list is accepted: restoring rebuilds each document's search projection from its card and body on disk, so the server has no unbounded form of it.
• aigo data document organize <ID>... [--add-collection <ID>]... [--remove-collection <ID>]... [--add-tag <TAG>]... [--remove-tag <TAG>]...: Apply collection and tag deltas across several documents at once. Unlike update, these are deltas: memberships not named are left alone.
• aigo data document reconvert <ID>: Re-run the converter against the stored original, producing a new body revision. The card is untouched.
• aigo data document refetch <ID>: Re-fetch a URL-sourced document. Returns the queued job.
• aigo data document summarize <ID> [--model <MODEL_ID>] [--overwrite-user-edits]: Queue an LLM draft of the card's summary and key points. Without --overwrite-user-edits a draft fills only fields that are empty or that a previous draft wrote. The request is accepted even when no model is available; the returned job then carries the reason, which is a state to render rather than a transport failure.
• aigo data document related <ID>: Show the [[handle]] link graph around a document: outgoing links, backlinks, and handles that resolve to nothing.
• aigo data document chunks <ID>: List the document's retrieval chunks, with their heading paths and the embedding models each has a vector for.
• aigo data document revisions <ID>: List the document's card revisions, newest first. The REVERTIBLE column says which ids revert will accept; a body revision carries no card snapshot and is refused.
• aigo data document revert <ID> <REVISION_ID> [-y]: Restore an earlier card revision.
• aigo data search <QUERY> [--collection <ID>] [--tag <TAG>] [--limit <N>] [--preset <PRESET_ID>]: Lexical search across the corpus. Plain terms are ANDed, "quoted phrases" match verbatim, and tag: / collection: prefixes inside the query are parsed out as filters rather than searched for literally. Trashed documents are dropped from the index on trash, so they never appear. --preset selects a retrieval preset, which supplies the collection scope and the lexical or hybrid mode.

--matching requires at least one of --status, --collection or --tag. --include-trashed is accepted alongside them but does not satisfy that requirement on its own: it widens the scope rather than narrowing it, so --matching --include-trashed alone would mean the whole corpus, which is what --all is for and what the required filter exists to keep unspellable.

Enum values come from the server's own types and are rejected as argument errors (exit 2) when misspelled:

• --status: processing, ready, warning, failed, trashed.
• --source: upload, url, folder, chat, agent, wiki. ingest --source omits wiki, which is reserved for pages the wiki pipeline maintains.
• --kind: markdown, text, html, pdf, docx, spreadsheet, code, presentation, workbook, word_processing, ebook, other.

Collections, tags, and retrieval presets¶

A collection is a named grouping a document belongs to; a tag is free-form and has no lifecycle of its own, so it exists exactly as long as one live document carries it. A retrieval preset is the scope, mode, and budget that search and grounding retrieve with. All three take typed flags, with --json <BODY> and --file <PATH> as the escape hatch.

• aigo data collection list (alias ls): List collections with their description, live-document count, sensitivity, and last update. A sensitive collection is kept out of implicit grounding and out of tool reads that do not name it, which is why it is a column rather than a detail.
• aigo data collection create --name <NAME> [--description <TEXT> | --description-file <PATH>] [--sensitive]: Create a collection. The name is normalized server-side (trimmed, internal whitespace collapsed) and rejected when it is already taken case-insensitively.
• aigo data collection update <ID> [--name <NAME>] [--description <TEXT> | --description-file <PATH>] [--clear-description] [--sensitive | --not-sensitive]: Patch a collection. --clear-description is the only way back to no description at all, so it conflicts with the two flags that set one. An invocation with no flag at all is an argument error.
• aigo data collection delete <ID> [-y] (alias rm): Delete a collection. Member documents are detached, never deleted; the response says how many lost the membership.
• aigo data collection summarize <ID> [--model <MODEL_ID>] [--start-offset <N>]: Queue LLM summary drafts for one round of the collection's documents that have none. A round is bounded, so the response carries nextOffset; feed it back through --start-offset to drain a collection larger than the scan window, which is also what keeps a document whose draft just failed from being picked up again immediately. There is no --overwrite-user-edits here even though GenerateSummaryRequest carries the field: the batch replaces it with false before it queues anything, because a bulk action is where an accidental mass overwrite of human-written cards would hurt most. Overwrite one card with aigo data document summarize <ID> --overwrite-user-edits, which the single-document path does honour.
• aigo data tag list (alias ls): List tags carrying at least one live document, with their counts.
• aigo data preset list (alias ls): List retrieval presets. The SCOPE column reads (all) for a preset with no collections, because an empty scope means every collection rather than none.
• aigo data preset create --name <NAME> [--collection <ID>]... [--mode <MODE>] [--wiki-pages <POLICY>] [--top-k <N>] [--token-budget <N>] [--embedding-model <MODEL_ID>]: Create a retrieval preset. Every field but the name defaults to the built-in preset's value. Without an embedding model the preset retrieves lexically whatever --mode says.
• aigo data preset update <ID> [--name <NAME>] [--collection <ID>]... [--all-collections] [--mode <MODE>] [--wiki-pages <POLICY>] [--top-k <N>] [--token-budget <N>] [--embedding-model <MODEL_ID>] [--clear-embedding-model]: Patch a retrieval preset. --collection replaces the whole scope, so name every collection the preset should keep; --all-collections widens it back to everything. --clear-embedding-model sets the model back to none, which JSON cannot express through the plain field.
• aigo data preset delete <ID> [-y] (alias rm): Delete a retrieval preset. The built-in preset cannot be deleted and the server refuses it by name.

Grounding, citations, and metrics¶

• aigo data grounding <QUERY> [--preset <PRESET_ID>] [--memory-budget-tokens <N>] [--grounding-fraction <F>] [--no-record-reference]: Build the grounding block a chat turn would inject for that message. Console output is the block text and nothing else, so aigo data grounding "load balancing" > block.md writes exactly what would have been injected; -o json gives the whole context, with the sources, the resolved budget, and the degradation reason. Why an empty block is empty goes to standard error, where a redirect cannot capture it. --memory-budget-tokens is what the caller would spend on memory injection this turn, and the server subtracts it from the joint budget. --no-record-reference builds a preview without stamping the documents as referenced.
• aigo data citation export [<DOC_ID>...] [--collection <ID>] [--format <FORMAT>] [--out <PATH>]: Render a bibliography from card bibliographic metadata, keyed by the document handle. With no selection the export covers every live document. Console output is the bibliography itself, so it can be redirected; --out <PATH> writes it to a file and prints the accounting instead (it is --out, not -o, which is the global output-format flag, and --out - means standard output rather than a file named -). Documents whose card carries nothing bibliographic still get a title-only entry and are named on standard error, as is an export that stopped at the server's ceiling of 2000 documents.
• aigo data metrics: Print the local Data Hub counters: per-format ingest outcomes, time to searchable, search usage, and per-tool call and approval counts. They are process-local and development-build-only; a release build reports Recording: disabled with structurally zero counts rather than pretending to have measured anything.

Narrowing a grounding build is --preset and nothing else. --collection, --tag and --limit would be the obvious flags and are deliberately absent: they belong to a retrieval request type no endpoint serves, and POST /data/grounding-context neither reads them nor rejects them, so a client sending them would have had them dropped in silence. Put the collection scope on the preset instead.

More enum values, rejected as argument errors (exit 2) when misspelled:

• --mode: lexical, hybrid.
• --wiki-pages: include, exclude, prefer.
• --format: bibtex, csl_json.

Pipeline commands¶

The operator half of the group: the ingest queue, URL ingest, folder import, watch folders, embeddings, the maintenance schedule, trash purge, the store doctor, backfill, and the generated wiki. Every create and update here also accepts --json <BODY> and --file <PATH>, and --file - reads the body from stdin under the same 1 MiB cap.

--follow subscribes to the Data Hub event stream (GET /data/events, see events) and re-reads the matching status endpoint whenever a relevant event arrives, printing only when something changes. The status endpoint stays the authority on what the state is; the event only says when to look. An idle stream still re-reads every thirty seconds, so a terminal transition that emitted nothing cannot strand the wait. Against a server without the streaming endpoints it falls back to polling every two seconds and says so on standard error.

Either way it exits 0 when the work finishes successfully and 3 when it fails, is cancelled, or stops waiting for an explicit resume, so a script can branch on the outcome of the work rather than on the outcome of the request. --timeout <SECONDS> bounds the wait and exits 3 naming what was still in flight; without it a follow waits indefinitely, which matters most for job list, where a job can sit non-terminal until somebody runs doctor --repair fail_stuck_jobs.

One behaviour differs between the two. On the stream, job list --follow sees each phase change while the job is still in flight, so a job that is queued and then fails is witnessed and exits 3. The polling fallback can miss that transition entirely between two polls, and then reports the failure as somebody else's earlier one.

• aigo data events [--types <A,B>] [--since <ID>] [--raw]: Follow every data:* event until Ctrl-C, without a status re-read. This is the whole corpus rather than one pipeline, which is what the per-command --follow waits narrow.
• aigo data job list [--follow] [--timeout <SECONDS>] (alias ls): List ingest jobs, newest first (ID, kind, file, status, progress, document, updated). The endpoint takes no filters and returns at most 200 rows, newest first, with no truncation flag, so a full page means "at least this many" and the command says so. --follow waits for that page to drain and exits 3 if a job it saw in flight ends failed; a job that was already failed when the follow started is somebody else's earlier failure and does not affect the exit status.
• aigo data job enqueue (--json <BODY> | --file <PATH>): Queue a document for asynchronous ingestion. The body is an IngestDocumentRequest, the same shape aigo data document ingest builds from typed flags; this command answers with the job rather than with the document, which does not exist yet.
• aigo data job retry <JOB_ID>: Re-run a failed job.
• aigo data backfill [-y]: Queue a re-ingest for documents whose body is missing or failed. It asks first: on a large corpus it occupies both conversion workers for a long time. The server queues at most 100 jobs per call and the action is resumable, so a run that hits the cap says so and re-running once those finish continues where it stopped.
• aigo data url ingest <URL> [--title <T>] [--tag <TAG>]... [--collection <ID>]...: Fetch a URL and store the page as a document. Only http:// and https:// are accepted, the URL is capped at 4096 characters to match the server, and the fetch passes the server's SSRF guard. Answers with the queued job, because nothing has been fetched yet.
• aigo data folder-import run <PATH> [--no-recursive] [--include-hidden] [--max-depth <N>] [--tag <TAG>]... [--collection <ID>]... [--restrict-to-permitted-folders] [--sync [--max-files <N>]] [--follow] [--timeout <SECONDS>]: Import a folder on the API host, one ingest job per file. Recursive by default. The server clamps --max-depth to 24 rather than refusing a larger value. --sync uses the legacy synchronous endpoint, which walks the whole folder inside the request and returns every skipped entry; it leaves no run record behind, so --follow is refused alongside it. --max-files requires --sync and is clamped into the range 1 to 500 there. The durable run has no file ceiling to set: it assigns maxFiles its own batch size before the request is stored and again on every resume, so a value sent to it is discarded, and a run told to stop at 50 files would walk the whole folder in batches instead. Stop a durable run with aigo data folder-import cancel <RUN_ID>.
• aigo data folder-import list [--limit <N>] (alias ls): List recent runs (ID, path, state, done/queued, failed, updated).
• aigo data folder-import show <RUN_ID> [--follow] [--timeout <SECONDS>]: Show one run in full, including its per-outcome counters. A run that stopped reports how to continue it, and says to start a new import instead when it hit its absolute safety ceiling, which is the one stopped state resume refuses.
• aigo data folder-import cancel <RUN_ID> [-y]: Stop a run's future batches. Documents already imported are kept.
• aigo data folder-import resume <RUN_ID>: Resume a paused or interrupted run.
• aigo data watch-folder list (alias ls): List watched folders (ID, path, recursive, enabled, tags, consecutive failures, last scan).
• aigo data watch-folder add <PATH> [--no-recursive] [--include-hidden] [--tag <TAG>]... [--collection <ID>]...: Watch a folder, so the maintenance schedule re-scans it. A scan is an ordinary folder import with the same walker and the same already-imported skip.
• aigo data watch-folder update <ID> [--recursive | --no-recursive] [--include-hidden | --no-include-hidden] [--tag <TAG>]... [--clear-tags] [--collection <ID>]... [--clear-collections] [--enable | --disable]: Patch a watched folder. The path is not patchable: a different folder is a different watch, and rewriting it in place would re-key the already-imported set a scan resumes from.
• aigo data watch-folder remove <ID> [-y] (alias rm): Stop watching a folder. Documents it already imported are kept, but re-adding the folder re-scans it from scratch.
• aigo data watch-folder scan: Scan every eligible watched folder now, without waiting for the schedule.
• aigo data embedding run [--preset <PRESET_ID>] [--model <MODEL_ID>] [--follow] [--timeout <SECONDS>]: Start the corpus embedding run. Without either flag it uses the built-in preset's embedding model. --follow re-reads the status for the model the run actually started with, including when the request came in through --json or --file.
• aigo data embedding status [--preset <PRESET_ID>] [--model <MODEL_ID>] [--follow] [--timeout <SECONDS>]: Show embedding progress: state, model, embedded, total, and the pending count that says whether another run is worth starting.
• aigo data embedding cancel [-y]: Ask the worker to stop. Vectors already written are kept and a later run resumes from there.
• aigo data maintenance show: Show the maintenance schedule, one row per scheduled task (watch, refetch, purge, wiki) plus the numeric settings and the timezone the cron expressions are evaluated in.
• aigo data maintenance set [--watch-enabled | --watch-disabled] [--watch-cron <EXPR>] [--refetch-enabled | --refetch-disabled] [--refetch-cron <EXPR>] [--refetch-min-age-hours <N>] [--refetch-batch-size <N>] [--purge-enabled | --purge-disabled] [--purge-cron <EXPR>] [--purge-retention-days <N>] [--wiki-enabled | --wiki-disabled] [--wiki-cron <EXPR>] [--timezone <TZ>]: Patch the schedule. Only the flags given are sent, and an invocation with none is an argument error. The four last-run timestamps are owned by the runner and have no flag, because the cadence measures from them.
• aigo data trash purge [<DOC_ID>... | --all | --retention-days <N>] [-y]: Permanently delete trashed documents and everything derived from them: the original, the body, the card, the chunks, the vectors, the revisions, and the links. Nothing restores them. With no scope it deletes whatever the configured retention window already makes eligible, and --retention-days 0 empties the trash exactly as --all does, so it is confirmed with the same wording. The three scopes are mutually exclusive because the server resolves them by precedence rather than refusing a combination, so a --all --retention-days 30 that parsed would empty the whole trash with the window silently dropped.
• aigo data doctor [--repair <KIND>]... [-y]: Check store integrity. With no --repair it only reports. prune_orphan_rows and complete_interrupted_purges remove data, and the confirmation names whichever of them was asked for.
• aigo data wiki build [--collection <ID>] [--language <LANG>] [--model <MODEL_ID>]: Build the wiki over a scope, redrafting every planned page. Absent --collection means the whole corpus, which excludes sensitive collections.
• aigo data wiki update [--language <LANG>] [--model <MODEL_ID>]: Redraft only the pages whose cited sources changed.
• aigo data wiki continue [--collection <ID>] [--language <LANG>] [--model <MODEL_ID>]: Draft the planned clusters the last run left without a page.
• aigo data wiki status: Show wiki-wide state: whether a model is available at all, page count, unwritten clusters, watermark, last build, and the job currently in flight.
• aigo data wiki pages (alias ls): List wiki pages (ID, handle, title, type, stale, cites, backlinks, generated). CITES counts the citations the persisted link mirror records, which is not the reader-facing count the desktop byline shows.
• aigo data wiki refresh <PAGE_ID> [--language <LANG>] [--model <MODEL_ID>]: Redraft one page.
• aigo data wiki related <PAGE_ID>: Show the documents a page cites and the pages citing it.

Every mutating wiki verb queues a job and answers with it, because drafting a page is a model call; on a local model a corpus build is minutes of the machine's attention, which is why the scheduled wiki update ships off. aigo data wiki status is what says whether a model is available, so a build that would produce nothing is visible before it is started.

--repair takes the server's own repair names, and a misspelling is an argument error (exit 2):

• reindex_search: rebuild the search projection from the card and body files on disk. Non-destructive.
• prune_orphan_rows: delete derived rows whose owner is gone. Destructive of regenerable data only.
• quarantine_orphan_files: move files with no owning document into a quarantine directory instead of deleting them.
• fail_stuck_jobs: mark non-terminal jobs failed so they stop reading as in-flight.
• complete_interrupted_purges: finish purges that were interrupted. Destructive, and only touches documents already marked for purging.
• resync_frontmatter: rewrite each drifted card file's title from SQLite.
• backfill_wiki_meta: register a wiki-sourced document the wiki pipeline lost track of.

memory - Memory Namespaces and Entries¶

Read and write the memory bank behind the desktop Memory page: namespaces, the entries in them, the context a chat turn injects, and the extraction and consolidation passes that maintain them. create and update commands take typed flags; --json <BODY> and --file <PATH> carry a full request body instead, and --file - reads it from stdin under the shared 1 MiB cap. An export document read by memory import or namespace import has its own 50 MiB ceiling, because it is a payload rather than a request body; POST /memory/import carries the same 50 MiB as a route-local limit, so anything the command will read the server will accept. There is no cap on how many memory banks or entries a document may carry: every count limit an import could apply is one an export can exceed, and a backup that cannot be restored is worse than a large one.

Namespaces and entries are addressed by their UUID id, which namespace list and entry list print in the first column.

Every command below wraps a Management API endpoint. The endpoint each one calls, its scope, its response shape, and the fields the server requires that the flags do not name are in the Memory API reference.

• aigo memory namespace list (alias ls): List namespaces (ID, name, status, description, updated).
• aigo memory namespace show <NS_ID>: Show one namespace in full.
• aigo memory namespace create (<NAME> | --name <NAME>) [--description <TEXT> | --description-file <PATH>]: Create a namespace. The description is optional here and always travels, as an empty string when omitted, because the server declares it as a required field.
• aigo memory namespace update <NS_ID> [--name <NAME>] [--description <TEXT> | --description-file <PATH>] [--enable | --disable]: Patch a namespace. Only the given fields are sent; an invocation with no flag at all is an argument error.
• aigo memory namespace delete <NS_ID> [-y] (alias rm): Delete a namespace and every entry in it.
• aigo memory namespace toggle <NS_ID>: Flip the namespace between enabled and disabled. The state is read first and the inverse is sent, so use enable or disable when a script needs an idempotent result.
• aigo memory namespace enable <NS_ID> / aigo memory namespace disable <NS_ID>: Set the state explicitly. A disabled namespace keeps its entries and stops contributing to injected context.
• aigo memory namespace clear <NS_ID> [-y]: Delete every entry in a namespace, keeping the namespace itself.
• aigo memory namespace consolidate <NS_ID> [--similarity-threshold <F>] [--max-entry-age-days <N>]: Run the lexical deduplication sweep over one namespace's auto-extracted entries. Either override may be given alone; the other stays at the server's default.
• aigo memory namespace export <NS_ID> [-o <PATH>]: Export a namespace and its entries as JSON, to standard output or to a file. The file is written readable only by its owner, because the export carries the memory entries verbatim. -o does not create directories: a parent that does not exist is an argument error, checked before the request.
• aigo memory namespace import (<PATH> | -): Import a single-namespace export document as a new namespace. The document is sent verbatim as text, so a file that is not JSON is rejected locally before the request, and a whole-store document is refused with a pointer to aigo memory import, which reports what it created, merged, skipped and refused.
• aigo memory entry list (<NS_ID> | --enabled) [--tag <TAG>] [--source auto|manual] [--query <TEXT>] [--limit <N>] [--offset <N>] [--sort created|updated] [--order asc|desc] (alias ls): List a namespace's entries, or with --enabled every entry belonging to an enabled namespace, which is the set injected context draws from. The two forms reach different endpoints and cannot be combined, and the filters apply only to the namespace form. --tag is an exact match on one of the entry's tags and --query a case-insensitive substring of its content; for ranked relevance across namespaces use aigo memory search instead. Passing any filter switches the response to a page carrying the total match count, so the footer reports what it is showing out of what matched; passing none returns the whole namespace in storage order. --limit defaults to 100 and is capped at 1000.
• aigo memory entry show <NS_ID> <ENTRY_ID>: Show one entry, including its tags and metadata.
• aigo memory entry create <NS_ID> (<CONTENT> | --content <TEXT> | --content-file <PATH>) [--source auto|manual] [--tag <TAG>]... [--metadata <JSON>]: Create an entry. --source defaults to manual, which is what a memory typed at a command line is; auto is for a script replaying what an extraction produced.
• aigo memory entry update <NS_ID> <ENTRY_ID> [--content <TEXT> | --content-file <PATH>] [--tag <TAG>]... [--clear-tags] [--metadata <JSON>]: Patch an entry. --tag replaces the whole tag set, so name every tag the entry should keep; --clear-tags empties it. An invocation with no flag at all is an argument error.
• aigo memory entry delete <NS_ID> <ENTRY_ID>... [-y] (alias rm): Delete one or more entries. One id deletes that entry; two or more go through the bulk endpoint, which rewrites the namespace once and reports the ids it could not find rather than stopping at the first, so a partly stale selection still removes the rest.
• aigo memory entry move <NS_ID> <ENTRY_ID>... --to <TARGET_NS_ID> (alias mv): Move entries to another memory bank. Each entry keeps its ID, content, tags, metadata and timestamps, which is what re-creating it elsewhere would lose. The target must exist and must not be the source. There is no confirmation prompt: a move is reversible by moving back.
• aigo memory export (<NS_ID> | --all) [-o <PATH>]: Export one memory bank, or every one of them with --all, as JSON to standard output or to a file. The whole-store document is {"version", "exportedAt", "namespaces"}, where each element carries a bank and its entries; a single bank writes the same {"namespace", "entries"} object memory namespace export writes. The file is written readable only by its owner on Unix, because it carries the memories verbatim; on Windows it inherits the directory's ACL. -o does not create directories: a parent that does not exist is an argument error, checked before the request. An invocation naming neither a bank nor --all is an argument error rather than a whole-store dump.
• aigo memory import (<PATH> | - | --json <BODY>) [--on-conflict merge|skip]: Import a document of either shape. --on-conflict applies to the whole-store shape only, where a bank is matched by name: merge (the default) appends the incoming entries to the stored bank, skip leaves it alone. Every imported bank and entry is stamped with a fresh ID, so importing the same document twice appends rather than overwrites. A bank whose description carries the reserved agent-experience marker is refused and reported, on both the incoming and the stored side, because the per-agent read-back resolves that marker into an agent's system prompt.
• aigo memory search <QUERY> [--namespace <NS_ID>] [--limit <N>]: Search entries across namespaces, returned best-first by relevance. --namespace restricts the search to one namespace and --limit caps the results.
• aigo memory stats: Print aggregate statistics: entry and namespace counts, the source and kind breakdowns, the estimated token total, and a per-namespace table. Agent-experience namespaces are reported separately and never fold into the headline totals.
• aigo memory context [--max-tokens <N>] [--no-record-reference]: Build the memory block a chat turn would inject. Console output is the block text and nothing else, so aigo memory context > block.md writes exactly what would have been injected; -o json gives the token and entry counts alongside it. Building a context normally stamps its entries as referenced, which feeds recency ranking, so pass --no-record-reference when reading it only to inspect it.
• aigo memory extract --messages-file (<PATH> | -) [--model <MODEL_ID>] [--target-namespace <NS_ID>] [--trigger-interval <N>] [--context-window <N>] [--max-context-tokens <N>] [--config <JSON>]: Run the extraction pipeline over a transcript. The file is a JSON array of {"role", "content"} objects, at most 100 of them, and is validated locally before the request. --config carries the whole ExtractionConfig and conflicts with the four typed overrides. The router must be running.
• aigo memory consolidation run [--model <MODEL_ID>]: Run an LLM consolidation pass over every eligible namespace, merging clusters of similar auto-extracted entries into canonical facts. Manual entries are never touched. Without --model the server resolves one from settings and the loaded pool, and refuses the run when nothing resolves.
• aigo memory consolidation status: Report whether a scheduled run is due, with the configured interval, the last run and attempt timestamps, and the last maintenance error if there was one.
• aigo memory ensure-model [--model <MODEL_ID>]: Load the extraction model if it is not already loaded, printing the outcome (alreadyLoaded, loaded, disabled, modelNotFound, insufficientRam, timedOut, failed).
• aigo memory events [--types <A,B>] [--since <ID>] [--raw]: Follow the memory:* stream as entries and namespaces change, until Ctrl-C. See events.

session - Session Management¶

Manage inference and squad-agent sessions (the global Sessions surface; distinct from aigo squad session).

• aigo session list: List active sessions.
• aigo session show <ID>: Show a session.
• aigo session terminate <ID> [-y]: Terminate an active session.
• aigo session alias <ID> <ALIAS>: Rename the model alias of a running LLM-serving session.
• aigo session diagnostics <ID>: Show a diagnostics snapshot.
• aigo session history list: List terminated-session history.
• aigo session history show <ID>: Show a history entry.
• aigo session history delete <ID> [-y]: Delete a history entry.
• aigo session history clear [-y]: Clear all history entries.

The live SSE tail (GET /api/v1/sessions/events) is not exposed as a aigo session command. Follow aigo events --types session:added,session:updated,session:removed instead, which reads the same three names off the shared bus. See events.

squad - Squad Management¶

Create, inspect, and edit multi-agent squads. create and update take typed flags; --json <BODY> and --file <PATH> carry a full request body instead, for fields the flags do not model (per-agent tool config, container execution mode). --file - reads the body from stdin. The 1 MiB cap applies to --file and to stdin; an inline --json body is bounded only by the shell's argument limit.

The whole group wraps the Management API's squad surface, documented endpoint by endpoint in Squads. On Unix the CLI prefers the Unix-domain socket named in the discovery file over TCP, so no endpoint flag is needed for a local instance. --output console|json|yaml is a global flag and must come before the command group (aigo --output json squad list); placed after it, clap rejects it as an unexpected argument. The console formatters are tables, and --output json is what to pipe into jq.

• aigo squad list: List squads (ID, name, status, agent count, planner, workspace).
• aigo squad show <SQUAD_ID>: Show a squad, including a table of its agents (ID, name, role, model, execution mode, memory).
• aigo squad create --name <NAME> --workspace <PATH> [--description <TEXT> | --description-file <PATH>] [--template <TEMPLATE_ID>] [--agent <SPEC>]... [--planner <AGENT>]: Create a squad.
• aigo squad update <SQUAD_ID> [--name <NAME>] [--description <TEXT> | --description-file <PATH>] [--workspace <PATH>] [--planner <AGENT_ID> | --clear-planner]: Update a squad. Only the flags given are sent; --clear-planner removes the planner.
• aigo squad delete <SQUAD_ID> [--delete-workspace] [-y]: Delete a squad. The workspace directory is kept unless --delete-workspace is given.
• aigo squad restore <WORKSPACE_PATH>: Restore a squad from a workspace manifest.

--template <TEMPLATE_ID> seeds the squad's agents from a squad template (aigo squad template list shows the IDs). The template's planner-role agent becomes the planner. A non-empty --agent list replaces the template's agents entirely.

--agent <SPEC> is repeatable and takes name[:role[:model]]:

• Role is one of planner, developer, reviewer, writer, or custom:<label>, and defaults to developer.
• Model is a model ID and may itself contain a colon (dev:developer:llama3:8b). A custom label may not, because the segment after it is read as the model; use --json for a label containing a colon.
• --planner accepts the name of one of the --agent entries, which is resolved to that agent before the request is sent, or an agent ID. It needs at least one --agent entry: with --template alone the template's planner-role agent is selected automatically, and the agent IDs a template produces are assigned by the server.

# From a template
aigo squad create --name demo --workspace /tmp/demo --template builtin-fullstack-dev-team

# From explicit agents
aigo squad create --name demo2 --workspace /tmp/demo2 \
  --agent lead:planner:qwen3-8b --agent dev:developer:qwen3-8b --planner lead

# Full request body from stdin
echo '{"name":"demo3","workspacePath":"/tmp/demo3"}' | aigo squad create --file -

squad agent - Squad Agent Lineup¶

Per-agent add, read, change, and remove under the existing aigo squad group. Before these commands the only way to change one agent was aigo squad update <ID> <JSON> with the whole lineup repeated.

• aigo squad agent list <SQUAD_ID> (alias ls): List the squad's agents (ID, name, role, model, execution mode, memory).
• aigo squad agent show <SQUAD_ID> <AGENT_ID>: Show one agent in full, including its system prompt and instructions.
• aigo squad agent add <SQUAD_ID> --name <NAME> [FLAGS]: Add an agent. --role planner|developer|reviewer|writer|custom:<label>, --model <MODEL_ID>, --description <TEXT>, --icon <EMOJI>, --system-prompt <TEXT> or --system-prompt-file <PATH>, --instructions <TEXT> or --instructions-file <PATH>, --tool <NAME> (repeatable), --memory / --no-memory, --execution-mode in_process|container, --from-profile <PROFILE_ID>.
• aigo squad agent set <SQUAD_ID> <AGENT_ID> [FLAGS]: Change one agent. The same flags as add except --from-profile, all optional, plus --clear-settings-overrides and --clear-container-config. Anything you do not pass is left unchanged.
• aigo squad agent remove <SQUAD_ID> <AGENT_ID> [-y] (alias rm): Remove an agent. Refused with a 409 when the agent is the squad's planner (clear plannerAgentId first) or is mid-flight in a chat session or a running execution.

--model and --tool replace a whole object server-side, so set reads the agent first and merges: --model keeps the agent's context and capability requirements and clears only the recorded provider (it belonged to the model being replaced), and --tool keeps the disabled list and the permission overrides. No other flag needs that round trip.

Every add and set also accepts --json <BODY> or --file <PATH> instead of the typed flags (--file - reads standard input). The two forms are mutually exclusive, and a body is capped at 1 MiB.

squad task - Managed Tasks¶

Task subcommands under the existing aigo squad group. Create and update take typed flags; --json <BODY> and --file <PATH> (- reads stdin) remain the escape hatch for a full request body.

• aigo squad task create <SQUAD_ID> --title <TEXT> (--description <TEXT> | --description-file <PATH>) [--priority low|medium|high|critical] [--depends-on <TASK_ID>]... [--assign <AGENT_ID>] [--max-retries <N>]: Create a task.
• aigo squad task update <SQUAD_ID> <TASK_ID> [--title <TEXT>] [--description <TEXT> | --description-file <PATH>] [--priority <P>] [--depends-on <TASK_ID>]... [--clear-depends-on] [--assign <AGENT_ID> | --unassign] [--max-retries <N>]: Edit a task. A running task accepts only --description, --priority, and --max-retries; a finished one accepts nothing (retry it instead).
• aigo squad task delete <SQUAD_ID> <TASK_ID> [--force] [-y]: Delete a task. --force cancels a running task first, and tasks that depended on it lose the dependency.
• aigo squad task retry <SQUAD_ID> <TASK_ID> [--force]: Re-queue a failed or cancelled task. --force grants one more attempt when the retry budget is spent.
• aigo squad task assign <SQUAD_ID> <TASK_ID> <AGENT_ID> / unassign <SQUAD_ID> <TASK_ID>: Move a task between agents, or take it off its agent.
• aigo squad task list <SQUAD_ID> [--status pending|ready|assigned|in_progress|review|done|failed|cancelled]: List tasks, optionally filtered by status.
• aigo squad task show <SQUAD_ID> <TASK_ID> / graph <SQUAD_ID>: Show one task, or the dependency graph.
• aigo squad task status <SQUAD_ID> <TASK_ID> <STATUS>: Move a task to another status.

squad execution - Running a Plan¶

Submit a request, then control the run while it is in flight. Every control acts between tasks: a task already running is never interrupted.

• aigo squad execute <SQUAD_ID> <REQUEST> [--auto-approve] [--wait | --follow]: Submit a request to the squad's planner. --wait polls the status every two seconds until the run reaches a terminal state or stops for approval. --follow subscribes to the squad's event stream before submitting and prints each step as it happens: planning, the plan, one line per task and wave, and the result. Without --auto-approve it prompts Approve this plan? [y/N/r(eject with feedback)] when the plan is ready and calls approve or reject for you; anything but an explicit y rejects. A completed run exits 0 and a failed, cancelled, or rejected one exits 3. The two flags conflict, and --follow falls back to --wait polling against a server without the streaming endpoints.
• aigo squad approve <SQUAD_ID> <EXECUTION_ID> [--plan-file <PATH>]: Approve the pending plan. --plan-file replaces the planner's task list first; the file holds either the whole request body ({"planOverride": {"tasks": [...]}}) or the override on its own ({"tasks": [...]}), and - reads standard input. A task may carry an id of your own choosing, and a dependsOn entry resolves against the ids of the plan the file describes, so a file can introduce several tasks and declare the order between them without knowing any id the planner minted. See the squad API reference for the rules a chosen id has to satisfy.
• aigo squad reject <SQUAD_ID> <EXECUTION_ID> --feedback <TEXT>: Reject the plan and send the planner back to work.
• aigo squad execution <SQUAD_ID> <EXECUTION_ID> [--follow]: Show the run: status and wave, the wave table (wave, task, title, assignee, status, attempts), the tasks an operator skipped, and the operator instructions the run carried. --follow then attaches to a run already in progress: it subscribes to the live stream first, replays the run's persisted event ledger as the backlog, and continues live from where the backlog ends, so nothing falls between the two sources and nothing is printed twice across the seam.
• aigo squad pause <SQUAD_ID> <EXECUTION_ID> / resume <SQUAD_ID> <EXECUTION_ID>: Hold the run before its next task, and let it continue. Both are idempotent.
• aigo squad steer <SQUAD_ID> <EXECUTION_ID> (<MESSAGE> | --file <PATH>) [--task <TASK_ID> | --agent <AGENT_ID>]: Send an operator instruction. Without a scope flag the instruction is a standing one and is appended to every later task turn; --task and --agent narrow it to one task or one agent. --file - reads the instruction from standard input.
• aigo squad skip-task <SQUAD_ID> <EXECUTION_ID> <TASK_ID>: Skip a task that has not started, so it is never dispatched. Refused for a task that is already running or finished.
• aigo squad retry-task <SQUAD_ID> <EXECUTION_ID> <TASK_ID>: Re-run a failed task in the current wave. Needs a running or paused execution.
• aigo squad cancel <SQUAD_ID> <EXECUTION_ID>: Cancel the run. Works while it is paused.

aigo squad events [<SQUAD_ID>] follows the same stream without submitting anything, and aigo squad message <SQUAD_ID> <AGENT_ID> <TEXT> --wait prints one agent's reply as it streams instead of returning a turn id. Both are described under events.

The controls act on a real run on both runtimes. execute runs the planner and, with --auto-approve, starts the executor; approve starts it otherwise. A headless aigo-server drives the run the same way the desktop app does: the planner is an LLM call through the server's router, and tools a task calls go through the same capability and policy gates as POST /api/v1/tools/execute, so a tool that needs the desktop app is refused with the reason the tool catalog advertises rather than attempted.

A plan override is a replacement, not a patch: a stored task the file does not name is removed, a task carrying an existing id keeps its identity, and one with no id is appended. Assignees must be agents of the squad, dependencies must resolve inside the resulting plan, and a cycle is rejected before the run starts.

EXEC=$(aigo --output json squad execute sq-1 "Refactor the parser" | jq -r .executionId)
aigo squad pause sq-1 "$EXEC"
aigo squad steer sq-1 "$EXEC" "Keep the public API unchanged"
aigo squad resume sq-1 "$EXEC"

squad workspace - Workspace, Files, and Activity¶

The shared directory the squad's agents work in, and the read commands over it.

• aigo squad workspace init <SQUAD_ID> <PATH>: Create the workspace directory and its plans/, tasks/, memory/, artifacts/, logs/, and sessions/ subdirectories.
• aigo squad workspace status <SQUAD_ID>: Show whether the workspace exists, is writable, and holds the expected layout.
• aigo squad workspace validate <PATH>: Check a candidate path before creating a squad on it. Read-only.
• aigo squad workspace clean <SQUAD_ID> [--archive] [-y]: Remove the workspace. --archive writes an archive first.
• aigo squad files <SQUAD_ID> [PATH]: List workspace files, PATH being workspace-relative.
• aigo squad cat <SQUAD_ID> <FILE_PATH>: Print one workspace file.
• aigo squad search <SQUAD_ID> <QUERY>: Search workspace file contents.
• aigo squad activity <SQUAD_ID> [--persisted]: Show the activity log. Without the flag only the in-memory buffer is returned, which is empty after a server restart; --persisted reloads logs/events.jsonl from the workspace first.

squad memory - Agent Memory¶

Each agent's Markdown memory file under memory/, divided into named sections.

• aigo squad memory init <SQUAD_ID>: Create the memory bank for the squad.
• aigo squad memory read <SQUAD_ID> <AGENT_ID>: Print one agent's memory.
• aigo squad memory sections <SQUAD_ID> <AGENT_ID>: List that agent's section names.
• aigo squad memory write <SQUAD_ID> <AGENT_ID> --section <SECTION> (--content <TEXT> | --from-file <PATH>) [--overwrite]: Append to a section, or replace it with --overwrite.
• aigo squad memory search <SQUAD_ID> <QUERY> [--agent <AGENT_ID>] [--section <SECTION>] [--case-sensitive] [--limit <N>]: Search across the squad's agents.

squad session - Agent Sessions and 1:1 Chat¶

A squad agent can hold a 1:1 chat session alongside plan execution, with its own persisted history.

• aigo squad session start <SQUAD_ID> <AGENT_ID> / stop <SQUAD_ID> <AGENT_ID>: Start or stop the agent's current session.
• aigo squad session status <SQUAD_ID> <AGENT_ID>: Show whether a session is running and what it is doing.
• aigo squad session list <SQUAD_ID> <AGENT_ID>: List the agent's stored sessions.
• aigo squad session new <SQUAD_ID> <AGENT_ID>: Start a fresh session, leaving the previous one stored.
• aigo squad session show <SQUAD_ID> <AGENT_ID> <SESSION_ID> / delete <SQUAD_ID> <AGENT_ID> <SESSION_ID> [-y]: Read or delete one stored session.
• aigo squad message <SQUAD_ID> <AGENT_ID> <TEXT>: Send a message to the agent in its current session.
• aigo squad conversation <SQUAD_ID> <AGENT_ID>: Print the agent's current conversation.

squad history - History, Analytics, Budget, and Emergency Stop¶

• aigo squad history list <SQUAD_ID>: List past executions.
• aigo squad history show <SQUAD_ID> <EXECUTION_ID>: Show one execution record.
• aigo squad history logs <SQUAD_ID> <EXECUTION_ID>: Show that execution's log lines.
• aigo squad history report <SQUAD_ID> <EXECUTION_ID>: Generate the Markdown report for it and print the path it was written to on the server.
• aigo squad analytics <SQUAD_ID>: Show tokens, costs, and throughput.
• aigo squad budget show <SQUAD_ID> / usage <SQUAD_ID>: Show the budget configuration, or the current run's usage against it.
• aigo squad budget set <SQUAD_ID> <BODY_JSON>: Replace the budget configuration.
• aigo squad emergency-stop <SQUAD_ID>: Cancel every non-terminal execution for the squad.

Neither event route has a CLI command yet: the live SSE stream (GET /api/v1/squads/{id}/events) and the per-execution typed ledger (GET /api/v1/squads/{id}/history/{eid}/events) are both read from the Management API directly. The CLI has no streaming transport today.

squad template - Squad Templates¶

A template is a reusable agent lineup without a workspace.

• aigo squad template list: List available templates.
• aigo squad template show <TEMPLATE_ID>: Show one template.
• aigo squad template import <FILE>: Import a template from a file.
• aigo squad template export <TEMPLATE_ID> [--output <PATH>]: Write the template JSON to stdout, or to a file.
• aigo squad template delete <TEMPLATE_ID> [-y]: Delete a template.
• aigo squad template save <SQUAD_ID> --name <NAME> [--description <TEXT>] [--icon <ICON>]: Save an existing squad's lineup as a new template.
• aigo squad template install --path <PATH> [--source-id <ID>]: Install a template from the shared registry catalog.

squad discussion - Discussion Rooms¶

Discussion-room subcommands under the existing aigo squad group.

• aigo squad discussion create --json <BODY>: Create a room (body carries squadId/topic).
• aigo squad discussion list <SQUAD_ID> / list-completed <SQUAD_ID>: List rooms.
• aigo squad discussion show <ID> / delete <ID> [-y]: Show or delete a room.
• aigo squad discussion start|pause|resume|stop <ID>: Control the orchestrator.
• aigo squad discussion post <ID> --message <TEXT>: Enqueue a message (or --json/--file).
• aigo squad discussion cancel-message <ID> <MESSAGE_ID>: Cancel a queued message.
• aigo squad discussion mode <ID> <MODE>: Set the mode (moderated/brainstorm).
• aigo squad discussion strategy <ID> [STRATEGY]: Set or clear the strategy override (moderated/brainstorm/roundRobin/autonomous; omit or none/clear to reset).
• aigo squad discussion turn-budget <ID> <N>: Set the turn budget.
• aigo squad discussion conclude <ID> [--force]: Synthesize a conclusion.
• aigo squad discussion handoff <ID>: Build a handoff request.
• aigo squad discussion export <ID> [--format <FMT>]: Export the transcript (markdown/json/plainText).
• aigo squad discussion analytics <ID>: Show discussion analytics.
• aigo squad discussion watch <ID> [--types <A,B>] [--since <ID>] [--raw]: Follow one room live: turn starts and ends, streamed content deltas, tool calls and results, posted messages, queue and status changes, and the synthesized conclusion. A delta that arrives out of order is dropped rather than printed twice. The watch ends when the room reaches completed, cancelled, or error, or on Ctrl-C.

autonomous - Autonomous-Agent Providers¶

The aigo autonomous group wraps the provider-level autonomous-agent REST API. It is for provider discovery, availability checks, gateway lifecycle control, model bridge sync, messaging, provider events, and Hermes-specific operator tasks.

Provider kinds are validated by the CLI before dispatch. Current accepted values are claw and hermes; any other value is rejected and the allowed values are printed.

Read commands:

• aigo autonomous providers: List providers registered by the API server.
• aigo autonomous availability: Show whether each known provider is usable in the current runtime, including unavailableReason when it is not.
• aigo autonomous capabilities <KIND>: Show the provider's declared capabilities.
• aigo autonomous environment <KIND>: Show runtime, image, gateway, and environment issue details.
• aigo autonomous gateway status <KIND>: Show gateway status and endpoint.
• aigo autonomous gateway logs <KIND> [--tail <N>] [--since <RFC3339>] [--follow]: Show recent gateway logs. --follow polls every two seconds until Ctrl-C, advances --since for timestamp-aware providers, and removes overlap from snapshot-only providers so old lines are not printed again.
• aigo autonomous channels <KIND>: List messaging channels.
• aigo autonomous channel messages <KIND> <CHANNEL_ID> [--limit <N>] [--before <MESSAGE_ID>]: List recent messages for one channel.
• aigo autonomous skills <KIND>: List provider skills.

Mutation and stream commands:

• aigo autonomous install <KIND> [--follow]: Install provider prerequisites. With --follow, the CLI subscribes to /autonomous/events before sending the install request and prints install_progress frames until verification reaches 100% or an error event arrives.
• aigo autonomous gateway start <KIND> --image <IMAGE> [--mount HOST:CONTAINER[:ro]]... [--timeout SECS] [--idle-timeout SECS] [--host HOST] [--port PORT]: Start the provider gateway from typed flags.
• aigo autonomous gateway start <KIND> --json <BODY> / --file <PATH>: Send a full gateway-start JSON body. The body must match the server's flattened GatewayStartOptions wire shape with top-level provider, containerConfig, host, and port keys.
• aigo autonomous gateway stop <KIND>: Stop the provider gateway.
• aigo autonomous gateway restart <KIND>: Restart the provider gateway with its current configuration.
• aigo autonomous skill enable|disable <KIND> <SKILL_ID>: Change one provider skill's enabled state.
• aigo autonomous models sync <KIND> --model <ID>...: Sync model IDs. Each ID is sent as a complete ModelSummary with displayName equal to the ID and contextWindow set to 0.
• aigo autonomous models sync <KIND> --json <BODY> / --file <PATH>: Send a full SyncModelsBody.
• aigo autonomous message <KIND> <CHANNEL_ID> <TEXT> [--idempotency-key KEY]: Send a message through a provider channel.
• aigo autonomous message <KIND> <CHANNEL_ID> --file <PATH> [--idempotency-key KEY]: Read message text from a file. Use - for stdin.
• aigo autonomous events [--types a,b] [--raw]: Follow provider events. --types accepts event tags such as install_progress; --raw prints the parsed event JSON instead of a compact console line.

Hermes profile commands:

• aigo autonomous hermes profile list: List Hermes profiles. ls is accepted as an alias.
• aigo autonomous hermes profile create --name <NAME> [--description <TEXT>]: Create a profile from typed flags.
• aigo autonomous hermes profile create --json <BODY> / --file <PATH>: Send a full CreateProfileRequest body. Use --description-file <PATH> when only the description should come from a file.
• aigo autonomous hermes profile activate <NAME>: Set the active Hermes profile.
• aigo autonomous hermes profile settings <NAME>: Show folder permissions and container limits for one profile.

Hermes MCP commands:

• aigo autonomous hermes mcp list: List registered MCP servers. ls is accepted as an alias.
• aigo autonomous hermes mcp add --id <ID> --name <NAME> --command <CMD> [--arg <ARG>]... [--env KEY=VALUE]... [--scope profile|user|system] [--disabled]: Register or replace an MCP server from typed flags.
• aigo autonomous hermes mcp add --json <BODY> / --file <PATH>: Send a full HermesMcpServer body.
• aigo autonomous hermes mcp remove <ID> [-y]: Remove an MCP server after confirmation. rm is accepted as an alias.
• aigo autonomous hermes mcp reload: Ask the running Hermes daemon to reload MCP registrations.

Hermes settings and approvals:

• aigo autonomous hermes permissions set <PROFILE> --allow PATH[:read|:read_write|:full][:recursive]...: Replace folder permissions for a profile.
• aigo autonomous hermes permissions set --json <BODY> / --file <PATH>: Send a full SetFolderPermissionsRequest body.
• aigo autonomous hermes limits set <PROFILE> [--cpu-shares <N>] [--memory-mib <N>] [--pids-limit <N>]: Replace container resource limits for a profile.
• aigo autonomous hermes limits set --json <BODY> / --file <PATH>: Send a full SetContainerLimitsRequest body.
• aigo autonomous hermes approvals list: List pending approval requests. ls is accepted as an alias.
• aigo autonomous hermes approvals history [--limit <N>]: List applied approval decisions.
• aigo autonomous hermes approvals decide <REQUEST_ID> (--approve | --deny [--reason <TEXT>]): Apply an approval decision.
• aigo autonomous hermes approvals decide --json <BODY> / --file <PATH>: Send a full ApprovePendingActionRequest body.
• aigo autonomous hermes approvals watch: Follow governance_event frames from /autonomous/events. When standard input is a TTY, the CLI prompts for [a]pprove, [d]eny, or [s]kip; otherwise it only prints events.

Hermes platform and migration commands:

• aigo autonomous hermes platform set <PLATFORM> --field KEY=VALUE...: Store platform credentials. Credential values are sent in the request body and are not printed.
• aigo autonomous hermes platform set <PLATFORM> --file <PATH>: Read credential KEY=VALUE lines from a file. Blank lines and # comments are ignored, and - reads standard input.
• aigo autonomous hermes platform set <PLATFORM> --json <BODY>: Send a full SetPlatformCredentialsRequest body. Supported platform values are whatsapp, telegram, slack, discord, imessage, signal, teams, matrix, mattermost, email, sms, dingtalk, feishu, wecom, bluebubbles, home_assistant, and google_chat.
• aigo autonomous hermes platform clear <PLATFORM> [-y]: Clear stored credentials after confirmation.
• aigo autonomous hermes platform test <PLATFORM>: Test stored credentials for a platform.
• aigo autonomous hermes migrate-claw --target-profile <NAME> [--preset user_data|full] [--dry-run]: Run the OpenClaw to Hermes migration.
• aigo autonomous hermes migrate-claw --json <BODY> / --file <PATH>: Send a full MigrateClawOptions body.

gateway start, models sync, and Hermes create/update commands intentionally reject typed flags when a raw JSON body is present. message rejects <TEXT> together with --file. These refusals avoid ambiguous request bodies.

engine container - Container Inference Engines¶

Containerized inference-engine sessions (vLLM / SGLang) under the existing aigo engine group.

• aigo engine container start --json <BODY>: Start a session (body carries engineId/modelId/modelPath).
• aigo engine container stop <SESSION_ID>: Stop a session.
• aigo engine container readiness [--json <BODY>]: Show the readiness report.
• aigo engine container logs <SESSION_ID>: Tail engine logs.
• aigo engine container image inspect <ENGINE_ID>: Inspect an image (presence, size, reference).
• aigo engine container image pull <ENGINE_ID> [--force]: Pull / update an image.
• aigo engine container image remove <ENGINE_ID> [-y]: Remove an image.

provider login / provider capabilities¶

Codex OAuth device flow and capability detection under the existing aigo provider group.

• aigo provider login start <PROVIDER_ID>: Start a device-flow login (returns verificationUri/userCode; tokens are stored server-side and never printed).
• aigo provider login poll <LOGIN_SESSION_ID>: Poll the device-token endpoint once.
• aigo provider login cancel <LOGIN_SESSION_ID>: Cancel a login session.
• aigo provider login revoke <PROVIDER_ID>: Revoke stored tokens.
• aigo provider capabilities show <ID>: Show cached provider capabilities.
• aigo provider capabilities detect <ID> [--force]: Detect provider-level capabilities.
• aigo provider capabilities detect-with-models <ID> [--force]: Detect provider plus per-model records.
• aigo provider capabilities models <ID>: List cached per-model records.
• aigo provider capabilities model <ID> <MODEL_ID>: Show one model's record.
• aigo provider capabilities model-detect <ID> <MODEL_ID> [--force]: Detect one model's capabilities.
• aigo provider capabilities override <ID> <MODEL_ID> --json <BODY>: Set a manual override (ModelCapabilityOverrideInput).

Examples¶

List all available models in JSON format:

aigo model list -o json

Load a model with custom GPU layers:

aigo loaded load "gemma-3n-E4B-it-Q4_K_M" --gpu-layers 33

Check system GPU status:

aigo system gpu

List installed extension skills as JSON:

aigo extension skill list -o json

Create and start a discussion room:

aigo squad discussion create --json '{"squadId":"sq-1","topic":"Release plan"}'
aigo squad discussion start <DISCUSSION_ID>

Start a containerized vLLM engine session:

aigo engine container start --json '{"engineId":"vllm","modelId":"org/model","modelPath":"/models/org/model"}'