agentc

CLI for agent-compose — register workflows, dispatch runs, manage secrets, and stream live execution logs.

Install

From npm (recommended):

npm install -g @agent-compose/cli
agentc init                   # install Claude Code skills (~/.claude/skills/)

Requires Node ≥ 20. Published via npm Trusted Publishing — every release is OIDC-authenticated by GitHub Actions; no long-lived publish tokens involved.

From a clone of this repo (contributor / dev install):

# Make sure ~/.bun/bin is on PATH (add to ~/.zshrc / ~/.bashrc)
export PATH="$HOME/.bun/bin:$PATH"

cd cli && bun link            # makes `agentc` available globally
agentc init --dev             # install Claude Code skills, including dev-only ones

The --dev flag installs additional skills (/ac:dev-setup, /ac:release) that live in cli/skills-dev/ and ship only with the source repo — not the npm tarball.

Or, without installing:

alias agentc="bun /path/to/agent-compose/cli/src/index.ts"

Authentication

Mint your first admin-scoped key from the dashboard (sign in via magic-link → Settings → API Keys → Create key), then save it locally:

agentc auth login ac_YOUR_KEY   # writes ~/.config/agentc/settings.json
agentc auth status              # show where the active key/url comes from
agentc auth logout              # remove the saved key

You can also set AGENT_COMPOSE_API_KEY directly as an env var.

The legacy ADMIN_KEY env-token bootstrap path has been removed entirely.

Commands

agentc register <workflow>      Bundle and register a workflow (-n NAME, -v VERSION,
                                --schedule CRON, --build to capture a snapshot environment)
agentc invoke   <template>      Dispatch a run; --follow to stream logs until settle
agentc list                     List registered templates (name + version per row)
agentc logs     <run-id>        Stream live events for a run (re-attaches via SSE)

agentc secrets list   <workflow>           List secret keys (metadata only)
agentc secrets set    <workflow> <key>     Set a secret value (prompts; stored in GCP)
agentc secrets delete <workflow> <key>     Delete a secret

agentc usage                    Current calendar-month usage rollup
agentc snapshot list            List the team's saved sandbox snapshots
agentc snapshot delete <run-id> Delete a saved snapshot

agentc auth login <key>         Save API key persistently
agentc auth logout              Remove the saved key
agentc auth status              Show where the active key/url is coming from

agentc keys create <name>       Mint a new ac_… key (requires admin-scoped caller key
                                via --admin-key or AGENT_COMPOSE_ADMIN_KEY).
                                --scopes read,invoke,admin   --expires-in 30d
agentc keys list                List your team's keys (same admin requirement)

agentc init                     Install Claude Code skills (~/.claude/skills/)
agentc init --dev               Also install developer-only skills from cli/skills-dev/
                                (clone install only — not bundled with the npm tarball)

To mint your FIRST admin key, sign in at <server-url>/login and use the dashboard's create-key dialog (one-time reveal). The CLI's keys subcommands then work against --admin-key <that-ac_…>.

Claude Code skills

After agentc init, the following slash-commands are available in any Claude Code session running inside this repo:

Public skills (shipped with both npm and clone installs — cli/skills/):

| Skill | What it does | |---|---| | /ac:setup | Walks first-time setup against an existing server | | /ac:tutorial | Hands-on tutorial — register, invoke, schedule, emit events, capture snapshots (~10 min) | | /ac:register | Bundle + register the current workflow | | /ac:invoke | Dispatch a registered workflow with input | | /ac:register-invoke | Register-then-invoke combo for fast iteration | | /ac:schedule | Create / list / delete cron schedules on a registered workflow | | /ac:logs | Tail logs for a running run | | /ac:events | Send / list run events | | /ac:snapshots | List / inspect / delete captured sandbox snapshots | | /ac:secrets | Manage per-workflow secrets | | /ac:generate-workflow | Scaffold a new workflow from a plain-English description | | /ac:generate-agent | Scaffold an agent prompt + iteration logic | | /ac:generate-runtime | Scaffold a custom runtime for an exotic model/API |

Dev-only skills (clone install only — cli/skills-dev/, install with agentc init --dev):

| Skill | What it does | |---|---| | /ac:dev-setup | Bootstrap the local Docker server + dashboard | | /ac:release | Cut a tagged release for the server, SDK, or CLI and watch CI deploy / publish |

Environment variables

| Variable | Description | Default | |---|---|---| | AGENT_COMPOSE_URL | Server base URL | https://api.agentcompose.ai | | AGENT_COMPOSE_API_KEY | Bearer key for everyday calls | — | | AGENT_COMPOSE_ADMIN_KEY | Admin-scoped ac_… key for keys create / keys list | — |

All commands also accept --url, --api-key, --admin-key flags. Flag values win over env vars; env vars win over ~/.config/agentc/settings.json; the global config wins over the built-in defaults.

Project-level overrides live in .agentc/settings.json (committed) and .agentc/settings.local.json (gitignored, per-developer). Both can pin the active environment via { env: "local" | "prod" | … } and a map of named env definitions.