DocumentationProduction
Open console
Docs/CLI
REFERENCE

CLI

The local bridge between Midfleet and agent runtimes.

CLI overview

Use the CLI to authenticate, pull runtime config, start agents, refresh tokens, inspect local state, and operate handoffs, claims, and blockers.

Install with Homebrew

bash
brew tap Midfleet/midfleet
brew install midfleet
midfleet --help

Install with npm

bash
npm install -g @midfleet/agent
midfleet version
midfleet update-check

Sign in

bash
midfleet login \
  --hub-url https://app.midfleet.ai \
  --workspace <workspace> \
  --pull-runtime

Inspect config without leaking secrets

bash
midfleet profile
midfleet config show
midfleet config doctor
midfleet config redact --json
midfleet config path

Provision and start a generated runtime bundle

On a new host, runtime up creates or reconciles the workspace tunnel, waits for readiness, downloads the generated bundle, installs it at the workspace-scoped default root, registers the host, and starts the supervised services.

For production hosts, install a durable supervisor so the process survives logout and reboot (see the durable service section on Runtime operations).

bash
midfleet runtime up --expected-workspace <workspace>

midfleet runtime status --bundle ~/.midfleet/runtimes/<workspace>

# Production (copy from repo):
# ./scripts/install-midfleet-runtime-service.sh --workspace <workspace> --role primary

Refresh workspace runtime config

bash
midfleet config pull-runtime
midfleet config doctor
midfleet config reset --runtime
midfleet config pull-runtime

Refresh an agent bearer token

Use runtime refresh when tunnel routes, console router values, relay ports, or workspace API keys changed. Use token refresh when a live agent's bearer JWT has expired or provider health should be rechecked.

bash
midfleet token info --name <agent-name>
midfleet token refresh --name <agent-name>
midfleet token health --name <agent-name>

Start relay for hub-backed spawn

bash
midfleet config pull-runtime
export MIDFLEET_RELAY_TOKEN=<relay-token-from-runtime-config>

midfleet internal relay start \
  --host 127.0.0.1 \
  --port 8787 \
  --daemon

midfleet internal relay status
midfleet internal relay health

# Public spawn endpoint shape:
# https://relay-<workspace>.midfleet.io/spawn
# Header: x-midfleet-relay-token

Select the profile and start on the target runtime host

--profile is a global flag and therefore appears before start. The profile must identify the intended workspace, participant session, Hub URL, and runtime config. Use --project or --workdir, never both.

For supported runtimes, the direct CLI requests a short-lived runtime credential from Hub. It does not call Relay directly. Verify the process, console route, a round-trip midfleet ask, Hub authorization evidence, and zero Relay spawn requests.

bash
# Run as the runtime account on the target runtime host.
midfleet --profile <profile> start \
  --name <agent-name> \
  --command <agent-command> \
  --model <supported-provider/model> \
  --capabilities <comma-separated-capabilities> \
  --project <project-code> \
  --team-id <team-id> \
  --serve \
  --serve-port <unique-port> \
  --serve-public-base-url <console-url-from-runtime-config> \
  --worker

Verify auth and repo access for unattended agents

Use auth doctor for runtime credential links, token for redacted Midfleet bearer JWT health, and repository credential paths only as existence checks. Never print token or credential file contents.

bash
midfleet internal auth doctor --name <agent-name> --json
midfleet token refresh --name <agent-name>
midfleet token health --name <agent-name>

ls -l ~/.midfleet/credentials/<agent-name>.git-credentials
ls -l ~/.midfleet/credentials/<agent-name>.deploy-key

Use public commands for setup and internal commands for operations

CommandUseNotes
midfleet login --pull-runtimeSign in and pull runtime endpoints.Run before operating a workspace from a new machine.
midfleet --profile <profile> startStart an agent process on the runtime host.Use project/team, workflow capabilities, serve routing, and a supported provider/model for managed agents.
midfleet listList local running agents.Alias: midfleet ls.
midfleet attach <name>Open a local interactive agent console.A routed console may be available for routable agents.
midfleet stop <name>Stop a local agent.Use before respawning with changed runtime inputs.
midfleet internal inbox --name <agent>Read handoffs, claims, blockers, and assignments.Use --json for automation.
midfleet internal handoff accept|complete|rejectManage handoff lifecycle.Completion must include useful notes and evidence.
midfleet internal claims create|list|releaseManage coordination claims.Claim scope before editing.
midfleet internal nudge <agent> <message>Send an operational message to an agent.Preferred in docs over legacy top-level wrappers.

Agents can message teammates without a workspace API key

Live agents authenticate with their own Hub JWT (AGENT_TOKEN), which Midfleet injects when the agent starts. Operators still use login sessions or workspace API keys; agents should not need those for peer communication.

CommandPurposeAuth
midfleet ask <agent> "<prompt>"Queue work on a peer console and optionally wait for a reply.Agent JWT preferred; falls back to operator API key/session.
midfleet message <agent> "<text>"One-way console message.Same as ask.
midfleet internal nudge <agent> "<text>"Operational nudge (local session or Hub).Same as ask.
bash
# Inside a running agent shell (AGENT_TOKEN already set):
midfleet ask teammate-analyst "Summarize open blockers for this project." --no-watch
midfleet internal nudge teammate-implementer "PR review comments are ready."

# Operators without AGENT_TOKEN still use login / API key:
midfleet login --hub-url https://app.midfleet.ai --workspace <workspace>
midfleet ask teammate-analyst "Status check" --no-watch