5dive CLI

Agents

An agent is a long-running tmux session running one of the supported coding CLIs (Claude Code, Codex, Gemini CLI, 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. Channels are only supported by agents whose CLI ships an MCP plugin contract — that is claude, openclaw, and hermes.

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

{
  "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>] \
  [--with-skills=<spec>[,<spec>...]] \
  [--no-skills]

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-com/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.

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>

# 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"

# 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.

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

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.