Complete reference for every supyagent CLI command, option, and in-chat command.

supyagent CLI Reference

The supyagent CLI is the primary interface for creating, managing, and interacting with agents. It is built with Click and requires Python 3.11+.

supyagent [OPTIONS] COMMAND [ARGS]

Global Options:

Flag	Description
`--version`	Show version and exit
`--debug`	Enable debug logging (hidden)
`--help`	Show help and exit

Setup and Initialization

`supyagent hello`

Interactive setup wizard -- the best way to get started. Alias: supyagent setup.

supyagent hello
supyagent hello --quick    # Non-interactive with sensible defaults

Flag	Description	Default
`--quick`, `-q`	Non-interactive setup with sensible defaults	`false`

`supyagent init`

Initialize supyagent in the current directory. Creates agents/ and powers/ directories and installs default tools.

supyagent init                  # Interactive wizard
supyagent init --quick          # Quick init (directories + tools only)
supyagent init --force          # Overwrite existing files
supyagent init --tools-dir my_tools  # Custom tools directory

Flag	Description	Default
`--tools-dir`, `-t`	Directory for tools	`powers`
`--force`, `-f`	Overwrite existing files	`false`
`--quick`, `-q`	Quick init without wizard	`false`

Agent Management

`supyagent new`

Create a new agent from template.

supyagent new myagent
supyagent new myagent --model openrouter/google/gemini-2.5-flash
supyagent new myagent --from existing-agent
supyagent new worker --type execution
supyagent new monitor --type daemon

Flag	Description	Default
`--type`, `-t`	Agent type: `interactive`, `execution`, `daemon`	`interactive`
`--model`, `-m`	Model provider string	Config `DEFAULT_MODEL` or `anthropic/claude-3-5-sonnet-20241022`
`--from`	Clone from an existing agent	None

`supyagent list`

List all available agents with their type and description.

supyagent list

`supyagent show`

Show details about an agent (type, model, temperature, tools, delegates, system prompt).

supyagent show myagent

`supyagent validate`

Validate an agent's configuration. Checks YAML syntax, required fields, model provider, delegate references, tool permissions, and service connectivity.

supyagent validate myagent
supyagent validate planner

`supyagent schema`

Show the full agent configuration schema with all YAML fields, types, defaults, and descriptions.

supyagent schema

Interactive Chat

`supyagent chat`

Start an interactive chat session with an agent.

supyagent chat myagent                    # Resume or start session
supyagent chat myagent --new              # Force new session
supyagent chat myagent --session abc123   # Resume specific session
supyagent chat myagent --verbose          # Show tool details and tokens
supyagent chat myagent --dry-run          # Show config and exit

Flag	Description	Default
`--new`	Start a new session	`false`
`--session`	Resume a specific session by ID or prefix	None
`--verbose`, `-v`	Show tool call details and token usage	`false`
`--dry-run`	Show system prompt and tool schemas, then exit	`false`

In-Chat Commands

All commands start with / and are available during a chat session:

Command	Description
`/help`	Show all available commands
`/image <path> [msg]`	Send an image with optional message
`/tools`	List available tools with name, description, and source
`/creds [action]`	Manage credentials (`list`, `set <name>`, `delete <name>`)
`/sessions`	List all sessions for the current agent
`/session <id>`	Switch to another session (supports prefix matching)
`/new`	Start a fresh session
`/delete [id]`	Delete a session (default: current session)
`/rename <title>`	Set a display title for the current session
`/history [n]`	Show last N messages (default: 10)
`/context`	Show context window usage, summarization trigger status
`/tokens`	Toggle token usage display after each turn
`/debug [on\|off]`	Toggle verbose debug mode
`/summarize`	Force context summarization
`/export [file]`	Export conversation to markdown
`/model [name]`	Show or change the current model
`/reload`	Reload tools (pick up new/changed powers)
`/clear`	Clear the screen
`/quit`	Exit the chat (aliases: `/exit`, `/q`)

Execution

`supyagent run`

Run an agent in execution mode (non-interactive, single task).

supyagent run summarizer "Summarize this text..."
supyagent run summarizer --input document.txt
supyagent run summarizer --input document.txt --output json
echo "text" | supyagent run summarizer
supyagent run api-caller '{"endpoint": "/users"}' --secrets API_KEY=xxx

Flag	Description	Default
`--input`, `-i`	Read task from file (use `-` for stdin)	None
`--output`, `-o`	Output format: `raw`, `json`, `markdown`	`raw`
`--secrets`, `-s`	Secrets as `KEY=VALUE` or path to `.env` file (repeatable)	None
`--quiet`, `-q`	Only output the result, no status messages	`false`
`--verbose`, `-v`	Show tool calls as they happen	`false`
`--no-stream`	Disable streaming output	`false`

`supyagent batch`

Run an agent on multiple inputs from a file.

supyagent batch summarizer inputs.jsonl
supyagent batch summarizer inputs.jsonl --output results.jsonl
supyagent batch summarizer data.csv --format csv

Flag	Description	Default
`--output`, `-o`	Output file (default: stdout)	None
`--format`, `-f`	Input file format: `jsonl`, `csv`	`jsonl`
`--secrets`, `-s`	Secrets as `KEY=VALUE` or `.env` path (repeatable)	None

`supyagent daemon`

Run an agent as a daemon (poll-based event processing).

supyagent daemon myagent
supyagent daemon myagent --interval 1m
supyagent daemon myagent --dry-run        # Run one cycle and exit
supyagent daemon myagent --secrets API_KEY=xxx

Flag	Description	Default
`--secrets`, `-s`	Secrets as `KEY=VALUE` or `.env` path (repeatable)	None
`--interval`, `-i`	Override poll interval (e.g., `30s`, `5m`, `1h`)	Agent config
`--verbose`, `-v`	Show detailed cycle output	`false`
`--dry-run`	Run one cycle and exit	`false`

`supyagent plan`

Run a task through the planning agent for orchestration.

supyagent plan "Build a web scraper for news articles"
supyagent plan "Create a data validation library" --planner my-planner
supyagent plan "Write a blog post" --new

Flag	Description	Default
`--planner`, `-p`	Planning agent to use	`planner`
`--new`, `-n`	Start a new session	`false`

`supyagent orchestrate`

Run a multi-agent workflow from a YAML file.

supyagent orchestrate workflows/daily-report.yaml
supyagent orchestrate workflows/pipeline.yaml --validate-only
supyagent orchestrate workflows/pipeline.yaml --output json

Flag	Description	Default
`--validate-only`	Only validate, do not run	`false`
`--output`, `-o`	Output format: `text`, `json`	`text`

`supyagent exec`

Execute an agent as a subprocess (used internally for delegation).

supyagent exec researcher --task "Find papers on AI"
supyagent exec summarizer --task "Summarize this text" --output json

Flag	Description	Default
`--task`, `-t`	Task for the agent to perform	(required)
`--context`, `-c`	JSON context from parent agent	`{}`
`--output`, `-o`	Output format: `json`, `text`	`json`
`--timeout`	Max execution time in seconds	`300`
`--depth`	Delegation depth (set by parent agent)	`0`

Sessions

`supyagent sessions`

List, search, name, export, and manage sessions for an agent.

supyagent sessions myagent                              # List sessions
supyagent sessions myagent --all                        # Include empty sessions
supyagent sessions myagent --search "project"           # Search by keyword
supyagent sessions myagent --name abc123 project-alpha  # Set alias
supyagent sessions myagent --export project-alpha       # Export session
supyagent sessions myagent --export abc123 --format json
supyagent sessions myagent --delete abc123              # Delete session
supyagent sessions myagent --delete-all                 # Delete all sessions

Flag	Description	Default
`--search`, `-s`	Search sessions by title keyword	None
`--delete`, `-d`	Delete a specific session by ID or prefix	None
`--delete-all`	Delete all sessions for this agent	`false`
`--name`, `-n`	Set a named alias for a session (`SESSION_ID ALIAS`)	None
`--export`, `-e`	Export a session (by ID, prefix, or alias)	None
`--format`, `-f`	Export format: `markdown`, `json`	`markdown`
`--all`, `-a`	Include empty sessions (fewer than 2 messages)	`false`

Tools

`supyagent tools list`

List all available tools (supypowers, service, and native).

supyagent tools list
supyagent tools list --agent myagent    # Filter by agent permissions

Flag	Description	Default
`--agent`, `-a`	Filter by agent's tool permissions	None

`supyagent tools new`

Create a new tool from template.

supyagent tools new github_api

Creates powers/github_api.py with a Pydantic-based template.

`supyagent tools test`

Test a tool outside of an agent.

supyagent tools test shell__run_command '{"command": "echo hello"}'
supyagent tools test files__read_file '{"path": "README.md"}'
supyagent tools test web__fetch -s API_KEY=xxx

Flag	Description	Default
`--secrets`, `-s`	Secrets as `KEY=VALUE` or `.env` file (repeatable)	None

Agent Instances

`supyagent agents`

List agent instances or inspect agent configuration. Running without subcommand lists all registered instances.

supyagent agents                  # List instances (default)
supyagent agents list             # Same as above
supyagent agents inspect myagent  # Show full assembled system prompt

`supyagent agents inspect`

Show the full assembled system prompt for an agent, including all injected sections (tool creation, resilience, cloud service, thinking guidelines).

supyagent agents inspect myagent

Configuration

`supyagent config set`

Set an API key (interactive menu or specific key).

supyagent config set                        # Interactive menu
supyagent config set OPENAI_API_KEY         # Set specific key (prompts for value)
supyagent config set MY_KEY --value "val"   # Set directly (not recommended)

Flag	Description	Default
`--value`, `-v`	Set value directly (visible in shell history)	None

`supyagent config list`

List all configured API keys (names only, not values).

supyagent config list

`supyagent config delete`

Delete a stored API key.

supyagent config delete ANTHROPIC_API_KEY

`supyagent config import`

Import API keys from a .env file.

supyagent config import .env
supyagent config import secrets.env --filter OPENAI

Flag	Description	Default
`--filter`, `-f`	Only import keys matching this prefix	None

`supyagent config export`

Export stored API keys to a .env file.

supyagent config export backup.env
supyagent config export backup.env --force

Flag	Description	Default
`--force`, `-f`	Overwrite existing file	`false`

Service (Cloud Integrations)

`supyagent connect`

Connect to supyagent service for third-party integrations via device authorization flow.

supyagent connect
supyagent connect --url https://custom.supyagent.com

Flag	Description	Default
`--url`	Service URL	`https://app.supyagent.com`

`supyagent disconnect`

Disconnect from supyagent service and remove stored credentials.

supyagent disconnect

`supyagent status`

Show connection status and available service integrations.

supyagent status

`supyagent inbox`

View and manage your AI Inbox (webhook events from connected integrations).

supyagent inbox                          # List unread events
supyagent inbox -s read                  # List read events
supyagent inbox -p github                # GitHub events only
supyagent inbox -i EVENT_ID              # View a specific event
supyagent inbox -a EVENT_ID              # Archive an event
supyagent inbox --archive-all            # Archive all events

Flag	Description	Default
`--status`, `-s`	Filter by status: `unread`, `read`, `archived`	None
`--provider`, `-p`	Filter by provider (e.g., `github`, `slack`)	None
`--limit`, `-n`	Number of events to show	`20`
`--event-id`, `-i`	Get a specific event by ID	None
`--archive`, `-a`	Archive a specific event by ID	None
`--archive-all`	Archive all events	`false`

`supyagent service tools`

List available service tools from connected integrations.

supyagent service tools
supyagent service tools --provider google
supyagent service tools --json

Flag	Description	Default
`--provider`, `-p`	Filter tools by provider	None
`--json`	Output as JSON	`false`

`supyagent service inbox`

View inbox events via the service subcommand.

supyagent service inbox
supyagent service inbox --status unread
supyagent service inbox --provider github
supyagent service inbox --json

Flag	Description	Default
`--status`, `-s`	Filter by status: `unread`, `read`, `archived`	None
`--provider`, `-p`	Filter by provider	None
`--limit`, `-l`	Max events to show	`20`
`--json`	Output as JSON	`false`

Skills

`supyagent skills generate`

Generate Claude Code skill files from connected service integrations.

supyagent skills generate
supyagent skills generate --stdout
supyagent skills generate -o custom/path/

Flag	Description	Default
`--output`, `-o`	Output directory	`.claude/skills/`
`--stdout`	Print to stdout instead of writing files	`false`

Process Management

`supyagent process list`

List running background processes.

supyagent process list
supyagent process list --all    # Include completed processes

Flag	Description	Default
`--all`, `-a`	Include completed processes	`false`

`supyagent process show`

Show details of a specific process (status, PID, start time, log file, command, metadata).

supyagent process show <process_id>

`supyagent process output`

Show output from a background process.

supyagent process output <process_id>
supyagent process output <process_id> --tail 100

Flag	Description	Default
`--tail`, `-n`	Number of lines to show	`50`

`supyagent process kill`

Kill a running background process.

supyagent process kill <process_id>
supyagent process kill <process_id> --force

Flag	Description	Default
`--force`, `-f`	Kill without confirmation	`false`

`supyagent process cleanup`

Remove completed/failed processes from tracking and clean old log files.

supyagent process cleanup

Diagnostics

`supyagent doctor`

Diagnose your supyagent setup. Checks supypowers installation, agents directory, API keys, default tools, sessions, config encryption, and agent registry.

supyagent doctor

`supyagent telemetry`

View telemetry data for an agent (tool call frequency, timing, error rates, token usage).

supyagent telemetry myagent
supyagent telemetry myagent --session abc123
supyagent telemetry myagent --json

Flag	Description	Default
`--session`, `-s`	Session ID (default: all sessions)	None
`--json`	Output raw JSON	`false`

Maintenance

`supyagent cleanup`

Clean up stale registry entries and optionally empty sessions.

supyagent cleanup
supyagent cleanup --max-age 48          # Prune entries older than 48 hours
supyagent cleanup --sessions            # Also delete empty sessions

Flag	Description	Default
`--max-age`	Prune active entries older than N hours	`24`
`--sessions`, `-s`	Also delete empty sessions (fewer than 2 messages)	`false`

Server

`supyagent serve`

Start the API server (Vercel AI SDK compatible). Exposes a streaming chat endpoint compatible with the AI SDK useChat() hook, plus REST endpoints for agents, sessions, and tools.

supyagent serve                                    # localhost:8000
supyagent serve --port 3001                        # Custom port
supyagent serve --host 0.0.0.0                     # All interfaces
supyagent serve --reload                           # Auto-reload on code changes
supyagent serve --cors-origin http://localhost:3000

Flag	Description	Default
`--host`	Bind host	`127.0.0.1`
`--port`, `-p`	Bind port	`8000`
`--reload`	Auto-reload on code changes	`false`
`--cors-origin`	Allowed CORS origins (repeatable)	`*`

Requires supyagent[serve] extra (pip install supyagent[serve]).

supypowers CLI -- Tool execution and documentation CLI
Configuration -- Config layers and management
Quickstart -- Get started in 5 minutes

supyagent CLI

On this page