5dive CLI

Agents

An agent is a long-running tmux session running one of the supported coding CLIs (Claude Code, Codex, Antigravity, Grok, openclaw, hermes, opencode). It owns its own Linux user, its own home directory, and — when paired — its own bot/app token. Two agents of the same type can coexist on one host.

Accounts (named auth profiles)

By default every agent of a given type shares one set of credentials, stored under /etc/5dive/connectors/<type>.env. To run two agents of the same type against different accounts, create a named account once and bind agents to it: 5dive account add personal, 5dive account login personal --type=claude, then --auth-profile=personal on agent create (or 5dive agent set-account <agent> personal after the fact). See Accounts for the full surface. The lower-level auth set --auth-profile=<name> and auth login --auth-profile=<name>verbs still work and back the dashboard's device-code flow.

Channels

A channel is the inbound message surface the agent listens on. Today: telegram, discord, or none. Every agent type supports Telegram — natively where the CLI ships an MCP plugin contract (claude, openclaw, hermes), and via a bundled 5dive bridge for the rest (codex, grok, antigravity, opencode). Discord is currently claude / openclaw / hermes only.

Workdir

The tmux session starts in the agent's workdir. Default is /home/claude/projects. Override at create time with --workdir=..., or change later with 5dive agent config <name> set workdir=....

Interactive login (TTY)

sudo 5dive agent auth login claude

Hands this process off to the upstream CLI's interactive flow. Don't use this from a dashboard; use the device-code variant below instead.

API key

# Direct
sudo 5dive agent auth set claude --api-key=sk-ant-...

# From stdin (recommended — keeps the key out of shell history)
echo "$KEY" | sudo 5dive agent auth set claude --api-key=-

Anthropic sk-ant-oat01-* tokens are routed to CLAUDE_CODE_OAUTH_TOKEN; everything else becomes ANTHROPIC_API_KEY.

Non-TTY device-code flow

The dashboard uses this flow because it runs without a PTY. Each call is async — start, poll until you get a URL, show the URL to the user, then submit the callback code the upstream login redirects to.

# 1. Start a session — returns a session id
sudo 5dive agent auth start claude --json
# -> {"ok":true,"data":{"session":"01HXX..","state":"awaiting_url"}}

# 2. Poll until state=awaiting_code; data.url is what the user opens
sudo 5dive agent auth poll 01HXX.. --json

# 3. User pastes the callback code from the redirect URL back to you
sudo 5dive agent auth submit 01HXX.. --code=anthropic#abc123

# 4. (optional) cancel a pending session
sudo 5dive agent auth cancel 01HXX..

Status

# Sentinel-only (fast)
sudo 5dive agent auth status

# Live probe — actually calls the API
sudo 5dive agent auth status --probe

# One type only
sudo 5dive agent auth status --type=claude --probe

Create and sign in

# 1. Create an empty account
sudo 5dive account add personal

# 2. Sign in interactively (TTY hand-off)
sudo 5dive account login personal --type=claude

# Or, set an API key non-interactively
echo "$KEY" | sudo 5dive agent auth set claude \
  --api-key=- --auth-profile=personal

Names: lowercase letters, digits, _, and -; must start with a letter; max 32 characters. The literal name defaultis reserved (it's the magic value agent set-account <agent> default uses to clear a binding).

Inspect

sudo 5dive account list           # name, types signed in, # agents bound
sudo 5dive account show personal  # detail incl. env keys present
sudo 5dive account usage          # per-account 5h/7d rate-limit usage

{
  "ok": true,
  "data": [
    { "name": "personal", "types": ["claude"], "agents": ["scout","builder"] },
    { "name": "work",     "types": ["claude","codex"], "agents": ["work-bot"] }
  ]
}

Bind agents

# At create time
sudo 5dive agent create scout --type=claude --auth-profile=personal

# After the fact (rebinds + restarts the agent to pick up the new env)
sudo 5dive agent set-account scout work

# Clear the binding (agent falls back to the shared default credentials)
sudo 5dive agent set-account scout default

Rename and remove

# Rename — repoints every bound agent's symlink and restarts the units
sudo 5dive account rename personal primary

# Remove — refuses if any agents still bind to it
sudo 5dive account remove primary

account remove is a safety net: if any agent has its authProfile set to the account, the command fails with class conflict (exit 5) and prints the agent names. Rebind or delete those agents first.

Account vs `agent auth` (lower-level)

The legacy agent auth set/login/start/poll/submit/cancel verbs still work — they take an --auth-profile=<name>flag and back the dashboard's device-code flow. Prefer account for human-driven flows; reach for agent auth start|poll|submit when you need the non-TTY device-code lifecycle from a programmatic caller.

Create

sudo 5dive agent create <name> --type=<type> \
  [--channels=none|telegram|discord] \
  [--telegram-token=<bot-token>] \
  [--discord-token=<token>] \
  [--workdir=<absolute-path>] \
  [--auth-profile=<name>] \
  [--isolation=admin|standard|sandboxed] \
  [--provider=<id> --api-key=<key|->] \
  [--with-skills=<spec>[,<spec>...]] \
  [--yolo | --autonomy=standard|yolo] \
  [--no-skills] [--no-team-bot] [--defer-auth]

Names: lowercase letters / digits / hyphens, must start with a letter, max 16 characters. The CLI installs the type binary on demand if it's missing, then refuses to create the agent unless the type is authenticated.

--with-skills preinstalls one or more skills on the new agent. Spec is either a bare id (defaults to 5dive-ai/skills) or <owner/repo>:<id>. Multiple specs are comma-separated. When the create call is made by another agent on a claude-typed agent, the flag defaults to --with-skills=5dive-cli so spawned children inherit inter-agent comms knowledge automatically. Use --no-skills to opt out. A failed skill install warns but does not roll back the agent — rerun 5dive agent skill <name> add ... to retry.

--defer-authskips the auth gate so the agent can be created before credentials exist (useful when the agent's own first-run UI handles sign-in). --provider=<id> --api-key=<key|-> is for hermes/openclaw only — BYO key for one of openrouter, google, minimax, moonshot, huggingface, anthropic, deepseek, qwen, nous, openai, zai (mutually exclusive with --defer-auth). When the host has a shared team bot configured, new no-bot agents auto-attach to it (own forum topic, send-only on the shared token) — --no-team-bot opts out.

--yolo (alias --autonomy=yolo) sets the agent's autonomy mode. claude-only: it appends a standing “act on your own recommendations, still honor hard gates” directive to the system prompt (via --append-system-prompt, so it survives a /clear) — the agent stops asking for permission on reversible work but still parks secrets/approvals on a human. Default is standard; change it later with agent config <name> set autonomy=....

List & inspect

sudo 5dive agent list                # text or --json
sudo 5dive agent stats <name>        # state, restart count, last exit
sudo 5dive agent logs <name> --lines=200 [--follow] [--tmux]

--tmux dumps the tmux scrollback (what the user sees in the TUI). Without it, logs come from systemd / journalctl.

Start, stop, restart, remove

sudo 5dive agent start   <name>
sudo 5dive agent stop    <name>
sudo 5dive agent restart <name>
sudo 5dive agent rm      <name>   # removes user, unit, tmux session, env

Reconfigure

sudo 5dive agent config <name> set channels=<none|telegram|discord>
sudo 5dive agent config <name> set workdir=<path>           # "default" clears
sudo 5dive agent config <name> set auth-profile=<name>      # "default" clears
sudo 5dive agent config <name> set telegram.token=<token>
sudo 5dive agent config <name> set discord.token=<token>
sudo 5dive agent config <name> set model=<id>               # claude/codex/grok/antigravity;
                                                            # claude: opus|sonnet|haiku|fable
sudo 5dive agent config <name> set effort=<low|medium|high|xhigh|max>
                                                            # claude only — reasoning effort;
                                                            # xhigh/max are Opus-tier
sudo 5dive agent config <name> set autonomy=<standard|yolo>
                                                            # claude only — yolo appends the "act on
                                                            # your recs, still honor hard gates" directive

# Shorter alias for the auth-profile case
sudo 5dive agent set-account <agent> <account|default>

Send input / attach

# Inject a message into the running tmux session (sends keys + Enter)
sudo 5dive agent send <name> "implement the dashboard skeleton"

# Hand off a chat request: tells the receiver to answer in that
# Telegram/Discord chat via its OWN bot instead of relaying back
sudo 5dive agent send <name> "user asks ..." --reply-to-chat=<id> [--reply-to-msg=<id>]

# Attach your terminal to the session — Ctrl-b d to detach
sudo 5dive agent <name> tui

When called from another agent, send auto-wraps the payload with a [5dive-msg from=<sender> id=<id>] envelope so the receiver knows who pinged it. Use --from=<label> to override and --raw to skip wrapping. See Inter-agent comms for the full protocol and the synchronous agent ask wrapper.

Clone

sudo 5dive agent clone <src> <dst> [--channels=...] \
  [--telegram-token=...] [--discord-token=...] [--workdir=...]

Clones type, workdir, and auth profile from <src>. Channel + tokens must be passed fresh — two agents cannot share a Telegram bot.

Team templates

Bundled multi-agent company structures — provision a whole team in one call. team import wraps up, so it is idempotent too.

sudo 5dive team ls                                  # list bundled templates
sudo 5dive team import <slug|path> [--auth-profile=<name>]

Export

# Config-only pack (default — safe to share)
sudo 5dive agent export <name> --out=./mybot.tar.gz

# With persona memory — a two-phase, deny-by-default review gate
sudo 5dive agent export <name> --with-memory          # 1. writes a redacted DRAFT to review/edit
sudo 5dive agent export <name> --approve-memory=<dir> # 2. seals the reviewed memory into the pack

--with-memory never ships memory blind: phase one distills only reference/project knowledge facts (private user/feedback facts are excluded) into a draft directory for you to read and edit; nothing is packed until you re-run with --approve-memory=<draft dir>.

Marketplace & import

The character-pack registry (<org>/character-packs on GitHub) is a public catalogue of ready-made agent personas. Browse it, then import any entry by its bare slug into a fresh agent name:

# Browse the registry
sudo 5dive agent marketplace ls

# Import a published persona under a new name + your own bot
sudo 5dive agent import lilbro --as=scout \
  --channels=telegram --telegram-token=123456:ABC...

# Import from a local .tar.gz you were handed
sudo 5dive agent import ./mybot.tar.gz --as=scout

import takes either a registry slug or a local pack file and recreates the agent under --as=<name>. Because packs carry no secrets, you supply the new agent's own token / auth-profile / workdir at import time. Skills are re-added from their recorded refs (any skill not in a published repo is skipped and reported). The dashboard's Marketplace modal drives this same path.

Pairing

# Option A — give the user a 6-character code, they DM the bot, paste it back
sudo 5dive agent pair <name>                    # prints/returns code

# Option B — paste the bot's reply directly (dashboard flow)
sudo 5dive agent pair <name> --code=AB12CD

# Option C — seed access.json directly with a known Telegram user id
# (pairs with agent telegram-discover, which long-polls getUpdates and
# returns {userId, chatId, username} on the first inbound DM)
sudo 5dive agent pair <name> --user-id=<id> [--chat-id=<id>]

Allow-list

The plugin's allow-list lives at ~/.claude/channels/<channel>/access.json inside the agent's home. Pairing appends to allowFrom; rotate the bot token via 5dive agent config <name> set telegram.token=....

Auto-attributed sends

When the caller is an agent-* Linux user (i.e. one agent shelling out to talk to another), the CLI auto-detects the sender from $SUDO_USER and wraps the payload as:

[5dive-msg from=<you> id=<8-hex>] <your text>

Humans calling sudo 5dive agent send directly are unaffected — only sends from agent users get the envelope. Override with --from=<label> or skip wrapping entirely with --raw.

Replying

A receiver that sees a wrapped message replies the same way it would talk to anything else — by name. The [re=<id>] prefix is convention, not enforced; it lets the sender match replies when juggling several outstanding asks.

# Inside the receiver's session, after seeing
# [5dive-msg from=scout id=ab12cd34] please summarise the audit

sudo 5dive agent send scout "[re=ab12cd34] auth middleware looks clean except ..."

Synchronous request/response: agent ask

sudo 5dive agent ask <name> "<prompt>" \
  [--from=<sender>] \
  [--timeout=120] \
  [--idle-secs=5] \
  [--poll-secs=2] \
  [--json]

Sends the wrapped envelope, then watches tmux capture-pane after the marker line until the slice has been quiet for --idle-secs (default 5s) — at which point it returns the reply body. Times out with class timeout (exit 11) if the receiver never goes idle within --timeout.

{
  "ok": true,
  "data": {
    "name": "scout",
    "from": "coordinator",
    "msg_id": "ab12cd34",
    "reply": "auth middleware looks clean except for ..."
  }
}

Caveats

Idle-by-stability is heuristic. A receiver that streams progress continuously will keep ask awake until --timeout fires. For long agentic work, prompt the receiver for a terse final summary, or use plain send + logs and poll on your own schedule.

The reply is whatever was on screen. It includes any chrome the receiver CLI prints (cursor lines, status hints) — don't expect a clean JSON body unless the prompt explicitly asks for one.

No retries, no delivery confirmation. If the receiver crashed mid-reply you'll get a partial slice or a timeout, nothing in between.

When to use what

Fire-and-forget delegation: agent send, then poll agent logs --tmux at your own convenience. Need an answer before continuing: agent ask. Fan-out across N workers: loop agent send, or run several agent ask calls in parallel via & + wait.

Verify loops (maker → verifier)

A task can carry a declarative acceptance loop so “done” is proven, not just claimed. Attach acceptance criteria, a verify command, and (optionally) a separate verifier agent at create time:

5dive task add "ship the export endpoint" \
  --accept="returns 200 + a .tar.gz" \
  --verify="curl -fsS localhost:3000/export -o /tmp/o && file /tmp/o | grep gzip" \
  --verifier=reviewer --max-iters=3

5dive task verify <id|PREFIX-N> [--cmd="<command>"] [--no-done]
                                     # run the check; exit 0 => proven-done (flips to done)
5dive task reject <id|PREFIX-N> [--feedback="<what to fix>"]
                                     # verifier's FAIL verdict — bounce back to the maker
5dive task loops [--stuck] [--all] [--escalate-stuck]
                                     # board of active loops: iteration/cap + ⚠ stuck flag

With a --verifier(which must differ from the assignee), the maker's task done does not close the task — it hands off to the verifier, who grades against the criteria / runs task verify, then closes it on PASS or task reject --feedback= on FAIL (bounce back to the maker, or escalate to a human at --max-iters). The writer never grades itself. task loops is the observability view — --escalate-stuck pings the owning agent + the human on loops that have stalled.

Human task inbox

When an agent needs a decision, approval, secret, or a manual step only a person can do, it parks the task on a human instead of guessing:

5dive task need <id> --type=decision|secret|approval|manual \
  --ask="<one crisp question>" [--options=A|B] [--recommend="A"]
5dive task inbox                     # list ONLY human-gated tasks
5dive task answer <id> --value="..."   # record answer, unblock, ping the agent

The gate pings the owner (Telegram inline buttons when paired); answer clears it and wakes the owning agent to resume.

approval and secret gates are human-only: an agent-* caller is refused, and once gate-proof enforcement is on they require a --proof=<token>that only a real human tap mints — so a sudo-capable agent can't silently clear its own approval gate. Trusted UI paths (dashboard, the Telegram approve button) attach the proof automatically.

Org chart

A lightweight reporting structure over the agents on a host — who manages whom, and what each agent's role is. Dashboards and coordinator agents read it to route work.

5dive org set <agent> --manager=<agent> [--role=<text>] [--title=<text>]
5dive org tree                       # render the hierarchy
5dive org show <agent> | ls | rm <agent>

Heartbeat (wake-on-work)

Enrolled agents are woken only when they have queued tasks — one task per tick — instead of idling in a hot loop. The root cron driver is heartbeat tick.

sudo 5dive heartbeat on <name> [--every=<dur>] [--no-fresh]   # default 30m;
                                                              # /clear before each task unless --no-fresh
sudo 5dive heartbeat off <name>
sudo 5dive heartbeat ls              # enrolled agents + next wake + queued count
sudo 5dive heartbeat tick            # cron driver (root); wakes due agents with work