5dive-cli

---
name: 5dive-cli
description: Use the local `5dive` CLI on a 5dive runtime VM to spawn, inspect, send to, and tear down sibling agents. Trigger when the user wants a worker, sub-agent, side task, parallel run, fan-out, or to delegate — or names a sibling agent ("ask X", "ping X", "tell X", "hand off to X", "coordinate with X"); confirm it exists via `5dive agent list --json`, then `agent send`. Also for inspecting/restarting/pairing an existing agent, a machine-readable health check (`5dive doctor --json`), the host-shared task queue + org chart (`5dive task`, `5dive org`), recurring/scheduled work (`task add --recurring`, `5dive heartbeat`), parking a question on a human (`task need`), or declarative fleets (`5dive up`, `5dive team import`). When a request came over a chat channel (Telegram/Discord `<channel>` tag) and another agent should handle it, pass the chat context via `--reply-to-chat=<id> --reply-to-msg=<id>` so that agent replies from its own bot — don't relay. Always prefer `5dive` over running coding CLIs by hand.
---

# 5dive-cli

This skill teaches you to drive the `5dive` command on a 5dive runtime VM.
You are running inside one such VM. You can spawn additional agents on the
same host by shelling out to `sudo 5dive ...` and parsing the JSON envelope
it emits when you pass `--json`.

## When to use this skill

Use it whenever the work in front of you would benefit from a second pair of
hands — for example:

- The user asks for a "worker", "sub-agent", "another agent", or "side task".
- **The user names a specific sibling agent** — "redirect to marketing",
  "ask scout", "ping ops", "tell research", "coordinate with X", "hand off
  to X". First confirm the agent exists via `sudo 5dive agent list --json`,
  then `agent send` (and pass chat context if the request came from a
  channel — see "Delegating a request that came in over a channel" below).
- A long task could fan out into independent pieces (e.g. audit each route
  in parallel, run a different model on the same prompt, A/B two implementations).
- You need to keep one agent on a hot context while a second one investigates
  something orthogonal.
- The user wants to inspect / restart / pair / tear down an agent that
  already exists on the host.
- You need a machine-readable health check of the host's coding-CLI stack.
- You're coordinating work across several agents and want a shared to-do list
  or a reporting structure (`5dive task`, `5dive org`).
- Work should recur on a schedule (`task add --recurring`) or an agent should
  be woken only when it has queued work (`5dive heartbeat`).
- You're blocked on something only a human can provide — a decision, a
  secret, an approval (`5dive task need`).

If the user just wants you to do the work yourself, do not spawn an agent.

## Mental model

Everything the CLI does maps onto these resources on the host:

- One **agent** = one Linux user (`agent-<name>`) + one systemd unit
  (`5dive-agent@<name>.service`) + one tmux session (`agent-<name>`)
  running the chosen CLI in a restart loop.
- Auth is decoupled. You authenticate a *type* once; every agent of that
  type inherits the credentials via `EnvironmentFile`.
- A **channel** (`telegram` / `discord` / `none`) is the inbound message
  surface. All agent types support channels; each agent needs its own bot
  token.
- The CLI is idempotent and safe to call from another agent — your agent
  user is in the `claude` group and has `sudo 5dive ...` whitelisted.

Agent types on a current host: `antigravity codex claude openclaw hermes
grok opencode`. Run `sudo 5dive agent types --json` for what's actually
installed — the set changes between releases.

## Output contract — always pass `--json`

Pass `--json` as a global flag (anywhere on the command line). Stdout
becomes a stable envelope; progress lines stay on stderr.

```bash
sudo 5dive agent create scout --type=claude --json
```

Success:
```json
{ "ok": true, "data": { "name": "scout", "type": "claude", "created": true } }
```

Failure (exit code matches `error.code`):
```json
{ "ok": false, "error": { "code": 6, "class": "auth_required", "message": "..." } }
```

**Branch on `error.class`, not on the human message.** Classes:
`ok`, `usage`, `validation`, `not_found`, `conflict`, `auth_required`,
`not_installed`, `not_running`, `pairing`, `permission`, `timeout`, `generic`.

See `references/exit-codes.md` for the full table.

## Recipes

### Spawn a worker for a side task

```bash
# 1. Pick a unique name (lowercase letters/digits/hyphens, ≤16 chars,
#    must start with a letter). Check the registry first if you care:
sudo 5dive agent list --json | jq '.data.agents | keys'

# 2. Create the worker. --workdir scopes its tmux cwd; default is
#    /home/claude/projects.
sudo 5dive agent create worker-1 \
  --type=claude \
  --workdir=/home/claude/projects/myrepo \
  --json

# 3. Send it the task. tmux send-keys + Enter, so the text appears
#    in the worker's running CLI prompt.
sudo 5dive agent send worker-1 \
  "audit the auth middleware for OWASP A01 issues; report back as a markdown bullet list"

# 4. Poll its output until it goes idle. --tmux dumps the scrollback.
sudo 5dive agent logs worker-1 --tmux --lines=80

# 5. Tear it down when you're done — frees the systemd unit + Linux user.
sudo 5dive agent rm worker-1 --json
```

`agent clone <src> <dst>` copies an existing agent's type/config into a new
one — handy when you want a second worker shaped like the first.

#### Skill inheritance on agent-spawned children

When an agent (you, `SUDO_USER=agent-*`) creates another agent of any
supported type, the CLI auto-installs the `5dive-cli` skill into the child
so it inherits inter-agent comms knowledge. Humans creating from the
dashboard don't get this default. Override either way:

- `--with-skills=<spec>[,<spec>...]` — explicit list. Each spec is a bare id
  (defaults to `5dive-com/skills`) or `<owner/repo>:<id>`.
  Example: `--with-skills=5dive-cli,acme/skills:db-tools`.
- `--no-skills` — opt out, even when called from another agent.

#### Create-then-auth: `--defer-auth`

Use when you want the agent registered before its credentials are wired up
(e.g. the agent's own first-run UI will handle sign-in). Skips the auth gate
on `agent create`; combine with `--auth-profile=<name>` to bind a profile slot
that doesn't yet have a `combined.env`.

```bash
sudo 5dive agent create draft-bot --type=claude --defer-auth --json
```

#### BYO API key: `--provider` (hermes / openclaw only)

`hermes` and `openclaw` are bring-your-own-model harnesses. Pass the
upstream provider and key at create time (mutually exclusive with
`--defer-auth`):

```bash
sudo 5dive agent create cheap-bot --type=openclaw \
  --provider=openrouter --api-key=- --json   # key on stdin
```

Providers: `openrouter google minimax moonshot huggingface anthropic
deepseek qwen nous openai zai`.

### Tune a running claude agent: model + effort

```bash
sudo 5dive agent config worker-1 set model=claude-sonnet-4-6
sudo 5dive agent config worker-1 set effort=high
# effort: low|medium|high|xhigh|max — claude only; xhigh/max are Opus-tier.
# model= also works for codex/grok/antigravity agents.
```

`sudo 5dive agent info <name>` shows the resolved type, CLI version, model
and channel state for one agent.

### Fan out: same prompt, three different types

Useful for "let me see how Claude/Codex/opencode each approach this".

```bash
for type in claude codex opencode; do
  sudo 5dive agent create "fan-${type}" --type="${type}" --json
  sudo 5dive agent send "fan-${type}" "$PROMPT"
done

# Wait, then collect the last 200 lines of each:
for type in claude codex opencode; do
  echo "=== ${type} ==="
  sudo 5dive agent logs "fan-${type}" --tmux --lines=200
done

# Cleanup.
for type in claude codex opencode; do
  sudo 5dive agent rm "fan-${type}" --json
done
```

### Declarative fleets: compose + team templates

For more than a couple of agents, declare the fleet in a `5dive.yaml` and
let the CLI reconcile, docker-compose style:

```bash
sudo 5dive up         # bring up everything declared in ./5dive.yaml (idempotent)
sudo 5dive ps         # declared agents' state
sudo 5dive down       # tear down declared agents
sudo 5dive export     # dump the LIVE fleet to a v2 5dive.yaml (reverse direction)

# Bundled multi-agent company templates:
sudo 5dive team ls
sudo 5dive team import startup --json
```

Spec keys per agent: `type, channels, telegram_token, discord_token,
workdir, skills, no_skills, defer_auth, isolation, auth_profile, provider,
api_key`. Strings expand `${ENV_VAR}` from the process env and fail loudly
when missing.

### Recover from `auth_required`

```bash
# If create fails with error.class=auth_required, the type isn't authenticated.
# Two paths — pick by what credentials you have:

# A) Static API key in $KEY (preferred for automation)
echo "$KEY" | sudo 5dive agent auth set claude --api-key=- --json

# B) Device-code flow (when only a human can complete login)
sudo 5dive agent auth start claude --json
# -> session id; give the URL from `auth poll` to the user; they paste the
#    callback code back via `auth submit`.
```

Never call `5dive agent auth login <type>` from your own process — it
hands the TTY off to the upstream CLI's interactive flow and hangs your
agent. Use `auth start` / `auth set` instead.

### Multi-account: the `account` noun

A 5dive **account** is a named auth profile — one bag of credentials that any
number of agents can share via `--auth-profile=<name>`. Use it when the host
has more than one human / billing identity (e.g. work + personal Anthropic
sign-ins) and different agents should use different ones.

`5dive account ...` is the user-facing surface; the lower-level
`agent auth start|poll|submit|cancel` verbs are still what the dashboard's
device-code flow uses, and what you should use from a script.

```bash
# Inventory: which named accounts exist, what types each is signed into,
# and how many agents are bound to each.
sudo 5dive account list --json

# Per-account rate-limit headroom (5h + 7d windows) — check BEFORE moving
# agents around or blaming "quota" for a failure.
sudo 5dive account usage --json

# Detail for one account, including which env keys are populated.
sudo 5dive account show acme-prod --json

# Provision a new empty account, then sign it in (TTY-only — humans).
sudo 5dive account add acme-prod
sudo 5dive account login acme-prod --type=claude

# Rebind an existing agent to a different account. Restarts the agent so
# the new EnvironmentFile takes effect.
sudo 5dive agent set-account worker-1 acme-prod --json
sudo 5dive agent set-account worker-1 default --json   # clears the override

# Rename / remove. `remove` refuses while any agents are still bound.
sudo 5dive account rename acme-prod acme-staging --json
sudo 5dive account remove acme-staging --json
```

The reserved name `default` is rejected by `account add` / `rename` — at the
agent level, `auth-profile=default` already means "no override, use the shared
`/etc/5dive/connectors/<type>.env`".

### Pair a Telegram channel without a bot reply

`agent pair` accepts three input shapes:

```bash
# A) Classic — return a pairing code, user DMs the bot, paste the bot reply.
sudo 5dive agent pair worker-1 --json
sudo 5dive agent pair worker-1 --code=AB12CD --json

# B) Auto-detect — long-poll Telegram for the next inbound message and
#    seed access.json from whoever DMs the bot first. Useful in onboarding
#    flows where the user has the bot open already.
sudo 5dive agent telegram-discover --token="$BOT_TOKEN" --poll-secs=60 --json
# -> {found:true, userId, chatId, ...}; re-poll on {found:false}.
sudo 5dive agent pair worker-1 --user-id=<userId> --chat-id=<chatId> --json

# C) Bot identity for deep links — fast getMe lookup so the dashboard can
#    render a tappable t.me/<bot> link alongside the "send /start" prompt.
sudo 5dive agent telegram-getme --token="$BOT_TOKEN" --json
# -> {ok:true, data:{botId, username, firstName}}
```

`telegram-discover` and `telegram-getme` are read-only (no registry mutation,
no audit log) and do not require a bound agent.

To attach a bot to an agent **after** create:

```bash
sudo 5dive agent config worker-1 set telegram.token=<bot-token>
sudo 5dive agent config worker-1 set channels=telegram
```

Who may talk to the bot is governed by the agent's `access.json`. Read /
write it without touching the file by hand (the plugin re-reads per message,
no restart needed):

```bash
sudo 5dive agent telegram-access get worker-1 --json
echo '{"dmPolicy":"allowlist","allowFrom":[433634012],"groups":{}}' \
  | sudo 5dive agent telegram-access set worker-1
# Shortcut at config level: seed the allowlist without the pair-code gate.
sudo 5dive agent config worker-1 set telegram.allowed-users=433634012,5551234
```

A group chat the bot should reply in must be present in `groups{}` — without
it, replies into that group are dropped.

### Talking to other agents (inter-agent comms)

`agent send` and `agent ask` work as a tiny message bus between agents on the
same host. There is no separate channel — messages land in the receiver's
running CLI as if a human had typed them.

#### Sending: attribution is automatic

When you (an agent) shell out to `sudo 5dive agent send <name> "..."`, the CLI
sees that `$SUDO_USER` is `agent-<you>` and wraps the payload as:

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

so the receiver can tell it's being pinged by a peer agent and which one.
Override the inferred name with `--from=<label>`. Skip wrapping with `--raw`
(useful when you're piping a prompt that already has its own structure).

Humans running `sudo 5dive agent send` directly never get auto-wrapped — only
sends from `agent-*` users do.

**Quote the body in single quotes and keep backticks / `$()` out of it** —
the message passes through a shell, so unquoted substitutions execute on
your side and mangle the payload.

#### Receiving: recognise the envelope and reply by name

When a line like

```
[5dive-msg from=scout id=ab12cd34] please summarise the auth middleware audit
```

appears as your input, treat it as an inter-agent request. To reply, send
back to the named sender:

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

The `[re=<id>]` prefix is convention, not enforced — it lets the original
sender match your reply to their question when they're juggling several at
once. Drop it for casual back-and-forth.

#### One-shot synchronous calls: `agent ask`

If you want a request/response in one CLI call (no manual polling of
`agent logs`), use `ask`:

```bash
sudo 5dive agent ask scout \
  "list the OWASP A01 issues you found, one per line" \
  --timeout=180 --json
```

It sends the wrapped envelope, then watches `tmux capture-pane` after the
marker line and returns once the scrollback has been quiet for `--idle-secs`
(default 5s). Stdout (text mode) is just the reply body; in `--json` mode the
envelope is `{ok:true, data:{name, from, msg_id, reply}}`.

Caveats — read these before leaning on `ask`:

1. **Idle-by-stability is heuristic.** A receiver that streams progress
   continuously will keep `ask` awake until `--timeout` fires. If you're
   asking for something the receiver might narrate (long agentic work),
   prompt it for a terse final summary or use plain `send` + `logs`.
2. **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 asks for one.
3. **No retries, no delivery confirmation.** If the receiver crashed mid-
   reply you'll get a partial slice or a timeout, nothing in between.

#### Delegating a request that came in over a channel

If a user pings you on a Telegram/Discord chat where the target agent's bot
is **also** a member, do not relay the answer yourself. Hand the target
agent the chat context and tell it to post directly via its own bot —
attribution stays clean, the conversation reads naturally, and you stop
being a middleman.

The CLI has structural support for this: `--reply-to-chat=<id>` (and
optional `--reply-to-msg=<id>` for thread replies) stamps the envelope so
the receiver gets a machine-readable hint instead of relying on you
describing the chat in prose.

**Where the chat_id and message_id come from.** When the user's request
arrives via the channel plugin (Telegram or Discord), it's surfaced to you
wrapped in a `<channel>` tag whose attributes already carry exactly what
the flags want:

```
<channel source="plugin:telegram:telegram" chat_id="433634012" message_id="4671" user="..." ts="...">
redirect to marketing
</channel>
```

The mapping is one-for-one:

- `chat_id` attribute → `--reply-to-chat=<chat_id>`
- `message_id` attribute → `--reply-to-msg=<message_id>` (optional; threads the reply)

So the handoff looks like:

```bash
sudo 5dive agent send marketing \
  --reply-to-chat=433634012 --reply-to-msg=4671 \
  "User @alice asked your take on the Q3 launch copy. Reply in the chat
   via your own bot — do not reply back to me."
```

Receiver-side, the inbound envelope looks like:

```
[5dive-msg from=ops id=ab12cd34 reply-to-chat=433634012 reply-to-msg=4671] ...
```

When you see `reply-to-chat=<id>` on an incoming message, post your answer
directly in that chat via your own Telegram/Discord tool. Use
`reply-to-msg=<id>` as the threaded `reply_to` so the message lands as a
quote-reply. Do not also send a peer reply back to the sender — they have
opted out of being a relay.

If the target agent's bot is **not** in the chat, omit the flag, relay the
reply yourself, and tell the user the bot needs to be added.

#### Rules of thumb

- For "fire-and-forget delegate, I'll check later": `agent send` + poll `agent logs --tmux` when it suits you.
- For "I need an answer to continue": `agent ask`.
- For broadcast / fan-out across N agents: loop `agent send` (or `agent ask` in parallel via `&` + `wait`). Each call is independent.
- Don't reuse `--from` labels for unrelated agents — pick a label that names *you*, so receivers can address replies correctly.
- When a request originates from a chat the target agent can post to, prefer direct reply over relay (see above).

### Track shared work: the task queue + org chart

When you fan work out across several agents, the host has a shared task queue
and an org chart so the team works off one source of truth. Both live in a
group-writable sqlite store (`/var/lib/5dive/tasks`), so **no sudo is needed** —
any `agent-*` user can read and write directly.

```bash
# Queue a unit of work and hand it to a worker. Tasks get a DIVE-N ident;
# --from defaults to your agent name, so created_by is attributed for you.
5dive task add "audit the auth middleware for OWASP A01" \
  --assignee=worker-1 --priority=high --json

# What's open, who's on what (priority-ordered); --mine filters to you.
5dive task ls --json
5dive task ls --mine --json

# Drive status as work moves. block/unblock express dependencies.
5dive task start DIVE-7 --json          # -> in_progress
5dive task done  DIVE-7 --result="one-line summary first; detail below" --json
5dive task block DIVE-9 --by=DIVE-7 --json   # DIVE-9 waits on DIVE-7

# Express who coordinates whom. --manager=default puts an agent at the top.
5dive org set worker-1 --manager=lead --title="Auth audit" --json
5dive org tree --json
```

On `done`/`cancel`, `--result` captures your outcome on the record and the
**first line** is what gets pinged to the owner's phone — lead with a terse
one-line summary, detail after the first newline.

A receiver that's assigned a task sees it via `5dive task ls --mine`; pair this
with `agent send` to actually nudge them. `task init` is a one-time root
bootstrap done at provision — never call it.

#### Park a question on a human: `task need`

When a task is blocked on something only a human can provide, don't sit on
it and don't guess — gate it:

```bash
5dive task need DIVE-12 --type=decision \
  --ask="Ship behind a flag or straight to prod?" \
  --options="flag|prod" --recommend="flag" --json
# --type: decision | secret | approval | manual
# -> task goes blocked; the human gets an alert with tap buttons.

5dive task inbox --json        # everything currently waiting on a human
5dive task answer DIVE-12 --value="flag" --json   # records + unblocks + pings the owner
```

Keep `--ask` to ONE crisp question with ~1 line of context; heavy detail
belongs in the task body. Always pass `--recommend` for decision/approval —
the alert leads with your recommendation so the human can one-tap it.

#### Recurring work + waking workers: heartbeat

A recurring **template** materializes into a normal todo on schedule; the
**heartbeat** wakes an enrolled agent only when it actually has queued work.
Use these instead of hand-rolling cron + `agent send`.

```bash
# Template: 5-field cron. Inert until it fires (excluded from ls/heartbeat).
5dive task add "rotate the weekly metrics digest" \
  --recurring="0 9 * * 1" --assignee=worker-1 --json
5dive task ls --recurring --json     # list templates

# Enrol the worker so the tick wakes it when tasks land. Default every=30m.
# fresh (default on) sends /clear before each task; --no-fresh keeps context.
sudo 5dive heartbeat on worker-1 --every=30m
sudo 5dive heartbeat ls              # enrolled agents + next wake + queued count
sudo 5dive heartbeat off worker-1
```

`heartbeat tick` is the root cron driver — already wired at provision; never
call it yourself. Enrolment uses the agent's **short name** (`worker-1`),
the same name `task --assignee` expects — not the Linux user `agent-worker-1`.
No catch-up for missed ticks: if the host is down over a scheduled minute,
that occurrence is skipped, so keep schedules coarse (hourly/daily).

### Diagnose a sick host

```bash
sudo 5dive doctor --json
```

Envelope is always `{ ok: true, data: { summary, checks } }` with exit 0.
Branch on `data.summary.errors > 0`. Add `--repair` to attempt reversible
fixes (apt installs, type installer recipes, registry reseed).

Other read surfaces worth knowing:

```bash
sudo 5dive agent stats --all --json   # whole fleet: unit state, restarts, health
sudo 5dive agent stats worker-1 --json
5dive update --check --json           # is the CLI behind/stale? read-only, no root
sudo 5dive watch                      # htop-style live view (interactive TTY only)
```

`5dive self-update` upgrades the CLI + plugins and **restarts every agent on
the host** — never run it casually from an agent session; managed boxes
update nightly on their own.

## Rules of engagement

1. **Always pass `--json`.** Parse the envelope. Don't grep stderr.
2. **One name = one agent.** Names are lowercase letters/digits/hyphens,
   start with a letter, max 16 chars. Reuse a name only after `agent rm`.
3. **Don't share bot tokens.** Two Telegram-channel agents on the same
   bot will race each other on `getUpdates`. Each agent needs its own.
4. **Tear down what you spin up.** A leaked `worker-N` agent stays
   running across reboots — it's a real systemd unit, not a thread.
   On task completion call `5dive agent rm <name>`.
5. **Don't shell out to the underlying CLI binaries directly.** Going
   around `5dive` skips the systemd unit, the audit log, and the env
   injection — the agent will run with broken auth and no restart loop.
6. **Read `5dive --help`** if a flag is rejected as unknown — the binary
   on the host may be newer or older than this skill. The help output is
   authoritative.
7. **The `auth login <type>` path is interactive only.** Never call it
   from your own session.
8. **When delegating a chat request, don't relay — hand off context.**
   If a user pings you in a Telegram/Discord chat that another agent's
   bot also belongs to and asks you to involve that agent, use
   `agent send --reply-to-chat=<id> --reply-to-msg=<id>` (values come
   straight from the inbound `<channel>` tag's attributes). The target
   replies directly in the chat from its own bot — relaying through you
   adds latency, breaks attribution, and makes the user re-read your
   paraphrase of the answer.
9. **Blocked on a human? Gate it.** Use `task need` with a recommendation
   instead of guessing or letting the task rot silently.

## Reference

- `references/commands.md` — every subcommand and flag, copy/pasteable.
- `references/exit-codes.md` — exit codes & error classes.
- `references/paths.md` — on-disk state layout (only for debugging).

## Going further

The full reference manual lives at <https://5dive.com/docs>. If a flag in
this skill conflicts with what the running binary accepts, trust the
binary — run `sudo 5dive --help` or `sudo 5dive agent <sub> --help`
directly and follow that.