CLI Reference

The agc command-line tool gives you full access to Agent Commons from your terminal, with secure browser sign-in, an interactive menu, streaming chat, and scriptable output.

Installation

npm install -g @agent-commons/cli

Running agc with no arguments opens the interactive menu:

agc

Use ↑ / ↓ to navigate and Enter to select. The menu covers chat, runs, sessions, agents, tasks, workflows, files, code projects, developer API keys, MCP, skills, wallets, usage, logs, and configuration.

If you have not signed in, the menu starts the sign-in flow.

Authentication

agc login

The CLI creates a short-lived device authorization request, opens Agent Commons in your browser, and waits for you to approve it. Your terminal never asks for your password.

If you are working on a remote host, print the approval URL instead:

agc login --no-browser

The CLI stores its account session in ~/.agc/config.json with file mode 0600. It refreshes short-lived API access tokens when needed.

Use a project API key

For CI and other non-interactive environments, pass a project-scoped csk_* key:

agc login --api-key "$AGC_API_KEY"

Create and scope project keys in Agent Commons → Settings → Developer API keys or with the agc keys commands after account sign-in. Treat keys as server-side secrets.

Other auth commands

agc logout       # clear locally stored credentials
agc whoami       # show the active account or API-key principal
agc config get   # show configuration with secrets masked

Environment variables

You can set credentials via env vars instead of running agc login:

export AGC_API_KEY=csk_your_project_key
export AGC_API_URL=https://api.agentcommons.io   # optional — this is the default
export AGC_AGENT_ID=agent_abc123                 # optional default agent

Env vars take precedence over the config file.

Developer projects and API keys

Developer API keys belong to a project, include explicit scopes, and can have an expiration date. The plaintext key is returned only when you create it.

agc keys projects list
agc keys projects create --name "Local development" --environment development
agc keys scopes
 
agc keys create \
  --name "CI deploy" \
  --project <projectId> \
  --scopes agents:read,agents:run \
  --expires 2027-01-01T00:00:00Z
 
agc keys list --project <projectId>
agc keys revoke <keyId>

Use agc api-keys as an alias for agc keys.

Agents

agc agents list                          # list your agents
agc agents get <agentId>                 # get agent details
agc agents create                        # interactive create
agc agents create \
  --name "My Bot" \
  --instructions "You are helpful." \
  --model-provider openai \
  --model-id gpt-4o
agc agents update <agentId> --temperature 0.5
agc agents delete <agentId>

Chat

agc chat opens an interactive streaming REPL. Each conversation is tied to a session so history is preserved.

agc chat --agent <agentId>                       # start a new session
agc chat --agent <agentId> --resume <sessionId>  # resume an existing session
agc chat --agent <agentId> --no-local            # disable local file system access
agc chat --agent <agentId> --no-stream           # wait for full response before printing

In-session slash commands:

Command	Description
/help	Show available slash commands
/session	Print the current session ID (for later resume)
/tools	Show local tools status and cached permissions
/clear	Clear the terminal screen
/quit	Exit — session is preserved for future resume

File context: prefix any path with @ to inject its contents into your message:

you › review @src/index.ts and suggest improvements

Set a default agent so you can skip --agent every time:

agc config set defaultAgentId agent_abc123
agc chat   # uses defaultAgentId automatically

Run (one-shot)

agc run sends a single prompt and exits. Useful for scripting, piping output, or quick one-off queries.

agc run --agent <agentId> "Hello"                 # stream response to stdout
agc run --agent <agentId> "Hello" --no-stream     # wait for full response
agc run --agent <agentId> "Hello" --json          # raw JSON event stream

Session flags

By default agc run is stateless — each call starts fresh. Use session flags when you need the agent to remember context across calls:

# Create a new session and print its ID
agc run --agent <agentId> "Summarise this repo" --new-session
# Session: ses_abc123 (new)
# ... response ...
# Session: ses_abc123  (resume with: agc run --session ses_abc123 "<prompt>")
 
# Resume that session in the next call
agc run --agent <agentId> "Now refactor main.ts" --session ses_abc123
# Session: ses_abc123 (resumed)
# ... response with full prior context ...

Flag	Description
`--session <id>`	Resume an existing session. Validates the ID before running.
`--new-session`	Create a new session, print its ID, use it for this run.

The session ID is printed at the end of every run that uses one, so you can copy it straight from the terminal.

Local file system flags

Give the agent direct access to files on your machine:

agc run --agent <agentId> "List all TypeScript files and summarise each" --local
# → prompts you before each write or shell command
 
agc run --agent <agentId> "Fix the lint errors in src/" --yes
# → auto-approves all operations — no prompts

Flag	Description
`--local`	Enable local file system access with per-operation confirmation prompts
`--yes` / `-y`	Enable local file system access and auto-approve all operations

All file operations are sandboxed to the current working directory. Sensitive paths (.ssh, .aws, .env, credentials) are always blocked regardless of flags.

When --local or --yes is active, the agent gains access to these tools:

Tool	Description
`cli_read_file`	Read a file (plain text, PDF, or Word doc)
`cli_write_file`	Write or overwrite a file
`cli_list_directory`	List directory contents
`cli_search_files`	Find files by name pattern
`cli_run_command`	Run a shell command and capture output
`cli_start_process`	Start a long-running background command
`cli_wait_for_process`	Wait for a background process and stream its output
`cli_process_status`	Check status of a background process
`cli_kill_process`	Kill a background process
`cli_list_processes`	List all background processes this session

Combining flags

# Research + remember context + work with files
agc run --agent <agentId> "Read package.json and list all dependencies" \
  --new-session --yes
 
# Resume with more work in the same session
agc run --agent <agentId> "Now check each dependency for known issues" \
  --session ses_abc123 --yes

Sessions

agc sessions list
agc sessions list --agent <agentId>
agc sessions get <sessionId>
agc sessions rename <sessionId> "New title"
agc sessions delete <sessionId>

Session logs from agc chat and agc run --local are written to ~/.agc/sessions/<sessionId>.jsonl. Each line is a JSON record of the message or tool call.

Tasks

agc task list
agc task list --agent <agentId>
agc task list --status running
 
agc task create \
  --title "Daily briefing" \
  --agent <agentId> \
  --input '{"topic":"overnight news"}'
 
agc task execute <taskId> --watch
agc task cancel <taskId>

Workflows

agc workflow list
agc workflow get <workflowId>
agc workflow create --file workflow.json
agc workflow run <workflowId> --input '{"url":"https://example.com"}' --watch

Library and code projects

agc library list
agc library upload ./report.pdf ./notes.md
agc library favorite <itemId>
agc library delete <itemId>
 
agc projects list --agent <agentId>
agc projects create --agent <agentId> --name "Dashboard"
agc projects write <projectId> files.json --agent <agentId>
agc projects publish <projectId> --agent <agentId>
agc projects export <projectId> --agent <agentId>

Set a default agent with agc config set defaultAgentId <agentId> to omit repeated --agent flags.

Tools

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

MCP Servers

agc mcp list
agc mcp add --name "GitHub Tools" --type sse --url https://mcp.example.com/sse
agc mcp add --name "Filesystem" --type stdio \
  --command "npx -y @modelcontextprotocol/server-filesystem /data"
agc mcp connect <serverId>
agc mcp sync <serverId>
agc mcp tools <serverId>
agc mcp disconnect <serverId>

Wallets

agc wallet list --agent <agentId>
agc wallet create --agent <agentId> --label main
agc wallet balance --agent <agentId>
agc wallet send --agent <agentId> --to 0xADDRESS --amount 5.0 --token USDC

Memory

agc memory list --agent <agentId>
agc memory create --agent <agentId> --type semantic --content "User prefers short answers"
agc memory search --agent <agentId> "user preferences"
agc memory delete <memoryId>

Models

agc models ls                   # all supported models
agc models ls --provider openai

Skills

agc skills list                   # all available skills
agc skills get <skillId>
agc skills create \
  --slug concise-review \
  --name "Concise review" \
  --instructions "Review changes and report actionable findings."

Usage and logs

agc usage agents
agc usage agent <agentId>
 
agc logs list --agent <agentId>
agc logs list --agent <agentId> --session <sessionId>
agc logs errors --agent <agentId>

Output formats

All commands default to human-readable output. Add --json for machine-readable JSON:

agc agents list --json
agc run --agent <agentId> "Hello" --json

Scripting

#!/bin/bash
# Run an agent and capture the result
RESULT=$(agc run --agent agent_abc123 "Summarize: $(cat input.txt)" --json)
echo $RESULT | jq '.response' > summary.txt
 
# Multi-turn scripted conversation using sessions
SESSION=$(agc run --agent agent_abc123 "Analyse this codebase" --new-session --yes 2>&1 \
  | grep "^Session:" | awk '{print $2}')
 
agc run --agent agent_abc123 "Now write a test for every exported function" \
  --session "$SESSION" --yes
 
agc run --agent agent_abc123 "Create a CHANGELOG.md summarising your changes" \
  --session "$SESSION" --yes
 
# Chain tasks
agc task execute task_123 && agc task execute task_456

CLI Reference

CLI Reference

Installation

Interactive menu

Authentication

Use a project API key

Other auth commands

Environment variables

Developer projects and API keys

Agents

Chat

Run (one-shot)

Session flags

Local file system flags

Combining flags

Sessions

Tasks

Workflows

Library and code projects

Tools

MCP Servers

Wallets

Memory

Models

Skills

Usage and logs

Output formats

Scripting

On this page