CLI Reference

The agh CLI is the operator surface for the local AGH daemon. Use it to bootstrap the home directory, start the daemon, create durable sessions, inspect workspaces, manage skills and extensions, and query runtime state over the daemon socket.

Rendering diagram...

The CLI groups commands by the runtime surface they operate: daemon process, durable work, project context, capabilities, observability, and local setup.

Command Groups

Agents

Inspect resolved agent definitions

Use this group to list available agents and inspect one resolved definition by name.

Discovery

Sessions

Create, resume, prompt, wait on, and inspect sessions

Use this group for durable agent work: `new`, `list`, `resume`, `events`, `history`, `status`, `prompt`, `wait`, and `stop`.

Core workflow

Tasks

Create tasks and operate task runs

Use this group for queued work, dependencies, child tasks, approvals, and run lifecycle.

Durable work

Workspaces

Use this group to add, list, inspect, edit, or remove workspace registrations.

Project scope

Daemon

Start, stop, and inspect the background runtime

Use this group for daemon lifecycle and socket-level health checks.

Runtime process

MCP

Authenticate and inspect MCP integrations

Use this group for remote MCP OAuth login, token status, refresh diagnostics, and logout.

Runtime integrations

Automation

Manage jobs, triggers, and runs

Use this group for scheduled work, event-triggered work, and run history.

Queued work

Hooks

Inspect hook catalog, events, and run history

Use this group when you need to understand what lifecycle hooks exist and how they executed.

Policy

Bridges

Manage platform bridge instances

Use this group for bridge instance creation, routing, lifecycle, and delivery tests.

External channels

Vault

Manage encrypted daemon Vault metadata

Use this group to list redacted metadata, write values from stdin, inspect one ref, and delete refs.

Secrets

Skills

Create, inspect, install, update, and remove skills

Use this group for local AgentSkills and marketplace-installed skill directories.

Agent capability

Memory

Read, write, search, and consolidate memory files

Use this group for persistent global or workspace memory and dream consolidation.

Durable context

Extensions

Install, enable, disable, update, and inspect extensions

Use this group for the extension marketplace and installed extension state.

Runtime plugins

Tools

Inspect and invoke registry tools

Use this group to list, search, info, and invoke tools through the operator projection. Agents call the same tools through the registry directly.

Tool registry

Toolsets

Inspect registry toolsets

Use this group to list and expand named toolsets such as agh__bootstrap, agh__catalog, and agh__autonomy.

Tool registry

Network

Inspect peers, channels, inboxes, and send envelopes

Use this group when a session participates in AGH Network coordination.

Coordination

Observe

Query health and global observability streams

Use this group for daemon health, global event history, and observability views.

Observability

Completion

Generate shell completion scripts

Use this group to install Bash, Zsh, Fish, or PowerShell completion for `agh`.

Shell setup

Bootstrap

Initialize ~/.agh and the default general agent

Use this command when you are setting up AGH on one machine for the first time.

First run

Identity

Inspect the agent identity exported into the current environment

Use this command inside managed sessions or automation when you need the current AGH identity envelope.

Environment

Version

Inspect the installed AGH build

Use this command to confirm the binary version before debugging or filing issues.

Build info

Global Options

The current CLI has one persistent flag inherited by every user-facing command.

Flag	Default	Values	Behavior
`-o, --output string`	`human`	`human`, `json`, `toon`	Selects output rendering. Use `json` for scripts and `toon` for compact agent-readable output.
`-h, --help`	n/a	n/a	Added by Cobra for every command. Prints command usage and exits.

There is no global --config, --log-level, or --socket flag today. These settings come from the AGH home directory and config.toml.

Input	Default	Effect
`AGH_HOME`	`~/.agh`	Overrides the global AGH home directory. This changes the default config path, socket path, log path, session store, skill store, and memory store together.
`~/.agh/config.toml`	created by `agh install`	Global configuration loaded by the daemon and most CLI commands before they contact the socket.
`[daemon].socket`	`$AGH_HOME/daemon.sock`	Overrides the Unix domain socket path used by daemon clients. Empty values fall back to the AGH home socket.
`[log].level`	`info`	Controls daemon structured logging. Accepted values are `debug`, `info`, `warn`, and `error`.
`[http].host`, `[http].port`	`localhost`, `2123`	Controls the daemon HTTP/SSE bind address exposed behind the runtime.
`AGH_SESSION_ID`	injected into managed agent sessions	Identifies the current AGH session for agent-side CLI calls and `agh whoami`.
`AGH_SESSION_CHANNEL`, `AGH_PEER_ID`	injected only for network-enabled sessions	Identify the joined network channel and daemon-owned peer identity for agent-side `agh network` calls.
`AGH_AGENT`, `AGH_AGENT_NAME`	caller-provided when present	Read by `agh whoami`; current session launch code does not synthesize these values.

Example: run a separate AGH home for a demo without touching your normal daemon.

AGH_HOME="$PWD/.agh-demo" agh install
AGH_HOME="$PWD/.agh-demo" agh daemon start
AGH_HOME="$PWD/.agh-demo" agh daemon status --output json

Example: set the daemon socket and log level in ~/.agh/config.toml.

[daemon]
socket = "~/.agh/custom-daemon.sock"

[log]
level = "debug"

Common Workflows

Start Daemon and Create a Session

Use this sequence after agh install has created a global config and a default general agent.

agh daemon start
agh workspace add "$PWD" --name current
agh session new --workspace current --agent general --name first-run

Then inspect the session and follow its event stream.

agh session list
agh session events sess_1234 --follow

The daemon start command waits until the socket responds. If a daemon is already running, it returns an error instead of starting a second process.

Resume a Session

Stopped sessions remain in the session store. List them with --all, resume by ID, and then inspect the new active state.

agh session list --all
agh session resume sess_1234
agh session status sess_1234

Resume succeeds only when the daemon can reconstruct the stored session state and the agent provider can load the previous ACP session. If the provider cannot resume, AGH reports the error rather than silently starting unrelated work.

Manage Workspaces

agh workspace add "$PWD" --name checkout-api --default-agent reviewer
agh workspace list
agh workspace info checkout-api

Edit the registration when the project moves or its default agent changes.

agh workspace edit checkout-api --name checkout
agh workspace edit checkout --default-agent ""
agh workspace remove checkout

agh session new --workspace <name-or-id> uses a registered workspace. agh session new --cwd <absolute-path> asks the daemon to use an absolute path directly and auto-register it when needed.

Shell Completion

Cobra generates completion scripts from the same command tree used for the reference pages.

Shell	Setup
Bash	`agh completion bash > "$(brew --prefix)/etc/bash_completion.d/agh"`
Zsh	`agh completion zsh > "$(brew --prefix)/share/zsh/site-functions/_agh"`
Fish	`agh completion fish > ~/.config/fish/completions/agh.fish`
PowerShell	`agh completion powershell > agh.ps1`

See the generated completion pages for shell-specific notes:

Full Command Tree

agh
|-- agent
|   |-- info <name>
|   `-- list
|-- automation
|   |-- jobs
|   |   |-- create
|   |   |-- delete <id>
|   |   |-- get <id>
|   |   |-- history <id>
|   |   |-- trigger <id>
|   |   `-- update <id>
|   |-- runs
|   |   `-- get <id>
|   `-- triggers
|       |-- create
|       |-- delete <id>
|       |-- get <id>
|       |-- history <id>
|       `-- update <id>
|-- bridge
|   |-- create
|   |-- disable <id>
|   |-- enable <id>
|   |-- get <id>
|   |-- list
|   |-- restart <id>
|   |-- routes <id>
|   |-- test-delivery <id>
|   `-- update <id>
|-- completion
|   |-- bash
|   |-- fish
|   |-- powershell
|   `-- zsh
|-- daemon
|   |-- start
|   |-- status
|   `-- stop
|-- extension
|   |-- disable <name>
|   |-- enable <name>
|   |-- install <path-or-slug>
|   |-- list
|   |-- remove <name>
|   |-- search <query>
|   |-- status <name>
|   `-- update [name]
|-- hooks
|   |-- events
|   |-- info <name>
|   |-- list
|   `-- runs
|-- install
|-- memory
|   |-- consolidate
|   |-- delete <filename>
|   |-- list
|   |-- read <filename>
|   `-- write <filename>
|-- network
|   |-- channels
|   |-- inbox
|   |-- peers [channel]
|   |-- send
|   `-- status
|-- observe
|   |-- events
|   `-- health
|-- session
|   |-- events <id>
|   |-- history <id>
|   |-- list
|   |-- new
|   |-- prompt <id> <message>
|   |-- resume <id>
|   |-- status <id>
|   |-- stop <id>
|   `-- wait <id>
|-- skill
|   |-- create [name]
|   |-- info <name>
|   |-- install <slug>
|   |-- list
|   |-- remove <name>
|   |-- search <query>
|   |-- update [name]
|   `-- view <name>
|-- task
|   |-- approve <id>
|   |-- cancel <id>
|   |-- child
|   |   `-- create <parent-id>
|   |-- complete <run-id>
|   |-- create
|   |-- dependency
|   |   |-- add <task-id> --depends-on <depends-on-id>
|   |   `-- remove <task-id> <depends-on-id>
|   |-- fail <run-id>
|   |-- get <id>
|   |-- heartbeat <run-id>
|   |-- list
|   |-- next
|   |-- publish <id>
|   |-- release <run-id>
|   |-- run
|   |   |-- attach-session <run-id>
|   |   |-- cancel <run-id>
|   |   |-- claim <run-id>
|   |   |-- complete <run-id>
|   |   |-- enqueue <task-id>
|   |   |-- fail <run-id>
|   |   |-- list <task-id>
|   |   `-- start <run-id>
|   |-- start <id>
|   `-- update <id>
|-- tool
|   |-- info <id>
|   |-- invoke <id>
|   |-- list
|   `-- search
|-- toolsets
|   |-- info <id>
|   `-- list
|-- version
|-- whoami
`-- workspace
    |-- add <path>
    |-- edit <name-or-id>
    |-- info <name-or-id>
    |-- list
    `-- remove <name-or-id>

The hidden agh doc command is intentionally excluded from the user-facing tree. It exists only so the repository can regenerate these reference pages.

On this page