CLI

agc — the Agent Commons command line. Chat, run, schedule, and ship from the terminal.

npm install -g @agent-commons/cli

Run agc with no arguments for an interactive menu, or use the commands below directly. Every list command accepts --json for scripting.

Signing in

agc login          # OAuth device flow — prints a code, opens your browser
agc whoami         # who am I, and can I reach the API?
agc logout         # clear stored credentials

Option	Purpose
`--api-key <key>`	Use a project key instead of the browser flow — for CI
`--no-browser`	Print the URL rather than opening it
`--api-url <url>`	Point at another Agent Commons deployment
`--identity-url <url>`	Point at another Commons Identity deployment
`--initiator <id>`	Delegated principal, for keys that permit it

Credentials go to ~/.agc/config.json with mode 0600. Access tokens refresh automatically before each command.

Configuration

agc config get
agc config set defaultAgentId agent_abc123

Settable keys: apiUrl, identityUrl, apiKey, initiator, defaultAgentId. Environment variables win over the file — AGC_API_URL, AGC_API_KEY, AGC_INITIATOR, AGC_AGENT_ID, COMMONS_ACCESS_TOKEN, COMMONS_IDENTITY_URL.

Set defaultAgentId once and every --agent flag below becomes optional.

Chatting

agc chat --agent agent_abc123
agc chat --resume session_xyz
agc chat --computer          # give the agent its cloud computer too
agc chat --no-local          # keep the agent out of your filesystem

An interactive REPL. Tokens stream, tool calls render inline, and the session is written to ~/.agc/sessions/<sessionId>.jsonl.

In-chat command	Effect
`/help`	List commands
`/tools`	Show the tools available in this session
`/session`	Print the current session ID
`/clear`	Clear the screen
`/quit`, `/exit`, `/q`	Leave — the session stays resumable

Local file access

agc chat exposes your working directory to the agent by default. The agent gets a live directory snapshot plus a set of cli_* tools that execute on your machine, not on the server:

Tool	What it does
`cli_list_directory`	List files and folders
`cli_read_file`	Read a file — PDFs and Word documents are extracted to text
`cli_write_file`	Write a file — asks you first
`cli_search_files`	Find files matching a pattern
`cli_run_command`	Run a short command — asks you first
`cli_start_process`	Start a long-running command in the background
`cli_wait_for_process` · `cli_process_status` · `cli_kill_process` · `cli_list_processes`	Manage background processes

Writes and commands require your confirmation. Sensitive paths — .ssh, .gnupg, .aws, .env, anything credential-shaped — are blocked outright. Git commits made through the agent carry a Co-Authored-By trailer naming the agent. Pass --no-local to switch all of this off.

One-shot runs

agc run --agent agent_abc123 "Summarise this week's AI policy news"
agc run --local -y "Refactor src/utils.ts and run the tests"
agc run --json "…" | jq -r 'select(.type=="token") | .content'

Option	Purpose
`--agent <agentId>`	Which agent
`--session <sessionId>`	Continue an existing session
`--new-session`	Start fresh and print the new session ID
`--local`	Enable local file access, with a prompt per write
`-y, --yes`	Enable local file access and auto-approve everything
`--computer`	Attach the agent's persistent cloud computer
`--no-stream`	Wait for the complete answer
`--json`	Emit the raw event stream as JSON lines
`--provenance <mode>`	`off`, `metadata` (default), or `full`
`--onchain-provenance`	Request an on-chain anchor for this run

Agents

agc agents list
agc agents get <agentId>
agc agents create --name "Research Bot" \
  --instructions "You research topics and answer with sources." \
  --provider anthropic --model claude-sonnet-4-6

`agents create` option	Default
`--name <name>`	required
`--instructions <text>`	—
`--provider <provider>`	`openai` — `openai`, `anthropic`, `google`, `groq`, `openrouter`, `xai`, `ollama`, `custom`
`--model <id>`	`gpt-5.4-mini`
`--model-api-key <key>`	Bring your own provider key
`--model-base-url <url>`	For custom or local OpenAI-compatible endpoints
`--runtime <runtime>`	`native` — or `openclaw`, `hermes`, `custom`

Heartbeat

agc agents autonomy status  --agent <agentId>
agc agents autonomy enable  --agent <agentId> --interval 3600
agc agents autonomy disable --agent <agentId>
agc agents autonomy trigger --agent <agentId>

Managed runtimes

agc agents runtime status  <agentId>
agc agents runtime deploy  <agentId>
agc agents runtime sleep   <agentId>
agc agents runtime restart <agentId>

Sessions

agc sessions list --agent <agentId>
agc sessions get <sessionId>
agc sessions create --agent <agentId> --title "Research" --model claude-sonnet-4-6
agc sessions rename <sessionId> "New title"
agc sessions delete <sessionId>

Tasks

agc task list --agent <agentId>
agc task create --agent <agentId> --title "Daily briefing" --execute --watch
agc task execute <taskId> --watch
agc task cancel <taskId>

`task create` option	Purpose
`--agent` · `--session`	Ownership and thread
`--workflow <workflowId>`	Attach a workflow instead of a single run
`--input <json>`	Input data — defaults to `{}`
`--timeout <ms>`	Execution timeout
`--execute`	Run immediately after creating
`--watch`	Stream progress over SSE — implies `--execute`

agc t is an alias for agc task.

Workflows

agc workflow list
agc workflow create --file workflow.json --name "Summarise a URL"
agc workflow run <workflowId> --input '{"url":"https://example.com"}' --watch
agc workflow executions <workflowId> --limit 10
agc workflow approve <workflowId> <executionId> <token>
agc workflow reject  <workflowId> <executionId> <token> --reason "Wrong source"

Templates

agc workflow templates list
agc workflow templates create <templateName> --agent <agentId> --run

Templates create the workflow and the API tools it needs. --prefix keeps generated names stable across re-runs. agc wf is an alias for agc workflow.

Tools

agc tools list
agc tools get <toolId>
agc tools create --file tool.json
agc tools exec <toolName> --args '{"city":"Nairobi"}' --agent <agentId>

MCP servers

agc mcp add --name "Filesystem" --type stdio \
  --command "npx @modelcontextprotocol/server-filesystem ~/projects"
agc mcp add --name "Docs" --type sse --url https://mcp.example.com/sse
agc mcp list
agc mcp connect <serverId>
agc mcp sync <serverId>
agc mcp tools <serverId>
agc mcp resources <serverId>
agc mcp read <serverId> <uri>
agc mcp prompts <serverId>
agc mcp prompt <serverId> <promptName> --args '{"topic":"pricing"}'
agc mcp remove <serverId>

Skills

agc skills list
agc skills index                 # compact, progressive-disclosure view
agc skills get <skillId>
agc skills create --slug weekly-report --name "Weekly report" \
  --description "Produce the standard weekly status report" \
  --tools webSearch,createDocumentFile
agc skills install <slug>        # print the skill as SKILL.md
agc skills publish <slug>
agc skills unpublish <slug>
agc skills update <slug> --description "…"
agc skills delete <slug> --yes

Connections

agc connections providers
agc connections connect google --scopes "https://www.googleapis.com/auth/gmail.send"
agc connections list
agc connections test <connectionId>
agc connections rename <connectionId> "Work Google"
agc connections refresh <connectionId>
agc connections revoke <connectionId>

Cloud computers

Each agent has exactly one persistent computer.

agc computer status  --agent <agentId>
agc computer enable  --agent <agentId>
agc computer wake    --agent <agentId>
agc computer exec    --agent <agentId> --cwd /workspace -- python analyse.py
agc computer sleep   --agent <agentId> --reason "done for now"
agc computer resize  --agent <agentId> --vcpu 4 --memory 16 --storage 100
agc computer events  --agent <agentId> --limit 20
agc computer disable --agent <agentId>

resize also accepts --profile, --mode, --gpu-type, and --gpu-count.

Library and files

agc library upload report.pdf notes.md --agent <agentId>
agc library list --query invoice --favorites
agc library get <itemId>
agc library favorite <itemId>
agc library delete <itemId>

--storage s3|ipfs picks the backend for an upload. agc files is an alias.

Code projects

agc projects create --name "Landing page" --agent <agentId> --files files.json
agc projects list --agent <agentId>
agc projects write <projectId> files.json --replace
agc projects publish <projectId>
agc projects export <projectId> --directory /workspace/site
agc projects github <projectId> --repository my-site --public

Common Arcade

agc arcade create --title "Comet Dodge" --agent <agentId>
agc arcade push <projectId> ./comet-dodge --runtime rules.js --thumbnail <url>
agc arcade test <projectId>
agc arcade publish <projectId>

See Common Arcade.

Memory

agc memory list --agent <agentId> --type semantic
agc memory search "formatting preferences" --agent <agentId>
agc memory create --agent <agentId> --content "Prefers bullet points" --type semantic
agc memory stats --agent <agentId>
agc memory delete <memoryId>

Wallets

agc wallet show    --agent <agentId>
agc wallet balance --agent <agentId>
agc wallet create  --agent <agentId> --label Primary
agc wallet send    --agent <agentId> --to 0x… --amount 5 --token USDC
agc wallet x402-fetch --agent <agentId> --url https://paid.example.com/data

Provenance

agc provenance session <sessionId>
agc provenance workflow <executionId>
agc provenance bundle <traceId> > provenance.json

Add --json to the first two for the complete machine-readable trajectory.

API keys

agc keys projects list
agc keys projects create --name "Production"
agc keys list
agc keys create --name "CI" --scopes agents:read,agents:run
agc keys scopes
agc keys revoke <keyId>

agc api-keys is an alias.

Usage, logs, and billing

agc usage agents --from 2026-01-01
agc usage agent <agentId>
agc logs list --agent <agentId> --status error
agc logs errors --agent <agentId>
agc credits balance
agc credits ledger --limit 50
agc billing status
agc billing upgrade pro
agc billing topup medium
agc models ls --provider anthropic

Scripting

--json on any list or get command prints machine-readable output.

agc agents list --json | jq -r '.[] | "\(.agentId)\t\(.name)"'
 
agc run --agent "$AGENT" --json "Draft the release notes" \
  | jq -r 'select(.type == "token") | .content' \
  | tr -d '\n'

For CI, authenticate with a project key and skip the browser entirely:

export AGC_API_KEY=csk_live_xxx
agc run --agent "$AGENT" --no-stream "Run the nightly summary"

On this page