CLI Reference

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

Installation

npm install -g @agent-commons/cli

Running agc with no arguments opens a full interactive menu — no commands to memorise:

agc

Use ↑ / ↓ arrow keys to navigate, Enter to select. The menu covers every feature: Chat, Run, Sessions, Agents, Tasks, Workflows, MCP, Skills, Wallet, Usage, Logs, and Config.

If no credentials are saved yet, the menu automatically launches the setup wizard.

Authentication

First-time setup

agc login

A three-step guided wizard runs:

API Endpoint — defaults to https://api.agentcommons.io. Press Enter to accept.
API Key — your browser opens automatically to agentcommons.io/settings. Generate a key there, paste it in the terminal.
Wallet address — your 0x… identity used as the request initiator.

Credentials are stored in ~/.agc/config.json (mode 0600).

Other auth commands

agc logout            # clear stored credentials
agc whoami            # show config + verify API connectivity
agc config get        # show all config values
agc config set apiKey sk-ac-xxxx   # update a single value

Environment variables

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

export AGC_API_KEY=sk-ac-xxxx
export AGC_API_URL=https://api.agentcommons.io   # optional — this is the default
export AGC_INITIATOR=0xYourWalletAddress
export AGC_AGENT_ID=agent_abc123                 # optional default agent

Env vars take precedence over the config file.

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>

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" \
  --description "Summarize overnight news" \
  --agent <agentId> \
  --cron "0 8 * * 1-5" \
  --recurring
 
agc task execute <taskId>      # run immediately + stream output
agc task stream <taskId>       # stream status of a running task
agc task cancel <taskId>

Workflows

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

Tools

agc tools list
agc tools list --type mcp
agc tools list --type custom
agc tools create --file tool.json
agc tools invoke <toolId> --input '{"city":"Nairobi"}'
agc tools add-key <toolId> --value "sk-abc123" --label prod

MCP Servers

agc mcp list
agc mcp connect --name "GitHub Tools" --type sse --url https://mcp.example.com/sse
agc mcp connect --name "Filesystem" --type stdio \
  --command "npx -y @modelcontextprotocol/server-filesystem /data"
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 <walletId>
agc wallet transfer <walletId> --to 0xADDRESS --amount 5.0 --token USDC

Memory

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

Models

agc models list                   # all supported models
agc models list --provider openai
agc models info anthropic         # details about a provider

Skills

agc skills list                   # all available skills
agc skills get <skillId>
agc skills create --file skill.yaml

Usage & Logs

agc usage
agc usage --agent <agentId>
 
agc logs
agc logs --agent <agentId>
agc logs --task <taskId>

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

First-time setup

Other auth commands

Environment variables

Agents

Chat

Run (one-shot)

Session flags

Local file system flags

Combining flags

Sessions

Tasks

Workflows

Tools

MCP Servers

Wallets

Memory

Models

Skills

Usage & Logs

Output formats

Scripting

On this page