The CLI

Everything Handoff does is available from a terminal as handoff <command>, with --json output for scripts. This page explains the conventions; the reference at the end is generated from the installed command tree, so it always lists exactly the commands your version has.

Invocation

pip install -e . puts handoff on your path. python -m handoff.cli is the same program, useful inside a Makefile or a cron line that cannot rely on an activated environment:

0 8 * * 1-5  cd /path/to/Handoff && .venv/bin/handoff run inbox-triage-morning

The CLI reads the same .env as the app, seeds the five template workflows on first use, and writes to the same state directory — so a workflow you build in the browser is the one handoff run runs, and a chat you start in the terminal is the one the browser shows.

Conventions

Exit codes. 0 means it worked. 1 means it failed — a model call errored, a service refused. 2 means you asked for something that does not exist: an unknown workflow id, a bad argument.

--json. Every read-only command prints a table for people by default and a JSON document with --json, so handoff --json workflows list | jq works the way you expect. Streaming commands print their final event as JSON.

--workspace <id> scopes a command to one workspace; the default is your default workspace. --state-dir <path> points at a different state directory, which is how the test suite and a second instance stay out of your data.

Secrets never print. settings show and credentials list show masked values and fingerprints. credentials set reads the secret with a hidden prompt, or from an environment variable with --from-env, and never echoes it.

A tour

Running things. run <workflow_id> starts a run and prints its outcome when it completes or stops for you; --watch follows the run's events live — every tool call, every deferral, the decision it asks for — as HH:MM:SS kind text lines. runs lists recent runs; inspect <run_id> is the step table the Inspector page shows: node, kind, name, status, milliseconds.

Decisions. pending lists what is waiting on you with the agent's confidence and its one-line summary. decide <interrupt_id> <action> --note "why" answers one; the note becomes the learner's strongest signal. activity is the audit log.

Talking. ask "what is waiting on me" is one turn with the workspace assistant, streamed. chat is the same in a loop; /new starts a fresh chat and /quit leaves. build "every weekday at eight, triage my inbox" turns a sentence into a workflow, --activate switches it on and --run starts it immediately.

Voice. say "text" speaks through the configured provider and plays it, or writes a file with --out. listen file.wav transcribes a recording. talk --mic is push-to-talk in the terminal with spoken replies; without a microphone library it takes typed input and still speaks. See Talk.

Workflows and the workspace. workflows list and workflows show <id>; workspace export path.yml or path.zip, workspace import path, workspace list. See Workflows.

The platform. agents, mcp, skills, memory, credentials and schedules mirror the pages of the same names. mcp call <server> <tool> --args '{...}' invokes a tool on a live MCP server; credentials check runs the doctor check for one provider; rules lists what the gate is acting on.

Operating. serve starts the web UI; desktop opens the native window; doctor checks every credential with a real call; settings show prints the effective configuration, redacted; usage shows tokens and cost per model; version prints the version. share opens a Cloudflare quick tunnel through cloudflared when it is installed and prints the public URL. deploy agentcore runs the deployment described in Deploy; deploy site builds and publishes this site.

Examples

Run the morning triage and follow it:

handoff run inbox-triage-morning --watch

Answer everything that is waiting the same way:

handoff pending
handoff decide int_3f9a2c7b1d0e archive --note "cold outreach"

Check a fresh machine before the first scheduled run:

handoff doctor
handoff doctor gmail speech

Export a workspace and load it somewhere else:

handoff workspace export team.zip
handoff workspace import team.zip

Shell completion, for bash, zsh or fish:

handoff completion zsh > ~/.zfunc/_handoff

Reference

Generated from the installed command tree, so it lists exactly the commands this version of handoff has.

handoff — Describe it. Hand it off. It runs.

Global options:

  • --json — Print machine-readable JSON instead of tables
  • --workspace <id> — Act on this workspace (default: the default one)
  • --state-dir <path> — Where runs, rules and settings live (sets HANDOFF_STATE_DIR)

handoff ask

One question or instruction to the assistant.

handoff ask [-h] [--new] text [text ...]
  • <text>… — What to say
  • --new — Start a fresh chat instead of continuing

handoff chat

Talk to the assistant in a loop (/new, /quit).

handoff chat [-h] [--new]
  • --new — Start a fresh chat

handoff build

Turn one sentence into a workflow config.

handoff build [-h] [--activate] [--run] text [text ...]
  • <text>… — The chore, in plain words
  • --activate — Save it switched on
  • --run — Save it and run it now, watching

handoff run

Run a workflow now.

handoff run [-h] [--trigger TRIGGER] [--watch] [workflow_id]
  • [<workflow_id>] — default inbox-triage-morning
  • --trigger <trigger> — Recorded as the run's trigger type; default manual
  • --watch — Follow the run's events live

handoff runs

Recent runs, newest first.

handoff runs [-h] [--limit LIMIT] [--workflow WORKFLOW]
  • --limit <limit> — default 25
  • --workflow <workflow> — Only runs of this workflow

handoff inspect

Every model and tool step of one run.

handoff inspect [-h] run_id
  • <run_id>

handoff pending

List decisions waiting on you.

handoff pending [-h]

handoff activity

The audit log: what was done, by whom.

handoff activity [-h] [--limit LIMIT] [--run RUN]
  • --limit <limit> — default 25
  • --run <run> — Only this run's entries

handoff decide

Answer a pending decision.

handoff decide [-h] [--note NOTE] [--all] [interrupt_id] [action]
  • [<interrupt_id>] — The decision's id (see pending)
  • [<action>] — archive, file_ticket, draft_reply, skip…
  • --note <note> — Why — it becomes the rule that is learned
  • --all — Apply the action to every pending decision

handoff workflows

List, inspect, enable, disable, delete or export workflows.

handoff workflows [-h] <action> ...

Subcommands: list, show, enable, disable, delete, export

handoff workflows list

List saved workflows (the default).

handoff workflows list [-h]

handoff workflows show

Everything about one workflow.

handoff workflows show [-h] workflow_id
  • <workflow_id>

handoff workflows enable

Mark a workflow active so its schedule fires.

handoff workflows enable [-h] workflow_id
  • <workflow_id>

handoff workflows disable

Pause a workflow; its schedule stops firing.

handoff workflows disable [-h] workflow_id
  • <workflow_id>

handoff workflows delete

Delete a workflow and its schedule.

handoff workflows delete [-h] workflow_id
  • <workflow_id>

handoff workflows export

Write one workflow's config as JSON.

handoff workflows export [-h] workflow_id [path]
  • <workflow_id>
  • [<path>] — File to write (default: stdout)

handoff agents

List, inspect or run the workspace's agents.

handoff agents [-h] <action> ...

Subcommands: list, show, run

handoff agents list

Every agent in the workspace (the default).

handoff agents list [-h]

handoff agents show

An agent's prompt, tools and what it needs connected.

handoff agents show [-h] agent
  • <agent> — Agent id or name

handoff agents run

Run an agent on a prompt and watch it work.

handoff agents run [-h] agent prompt [prompt ...]
  • <agent> — Agent id or name
  • <prompt>… — What to ask it

handoff mcp

Tool servers: list, describe, call, probe, add, remove.

handoff mcp [-h] <action> ...

Subcommands: list, tools, call, probe, add, remove, enable, disable

handoff mcp list

Built-in registry plus servers you added (the default).

handoff mcp list [-h]

handoff mcp tools

The tools one server offers, with their schemas.

handoff mcp tools [-h] server
  • <server> — Server name or id

handoff mcp call

Call one tool and print what came back.

handoff mcp call [-h] [--args JSON] server tool
  • <server> — Server name or id
  • <tool>
  • --args <json> — Arguments as a JSON object; default {}

handoff mcp probe

Connect, list tools, record the outcome.

handoff mcp probe [-h] server
  • <server> — Server name or id

handoff mcp add

Register a server by command (stdio) or URL (http).

handoff mcp add [-h] [--command COMMAND] [--args [ARGS ...]] [--url URL] [--env [VAR ...]] [--description DESCRIPTION] name
  • <name>
  • --command <command> — Executable for a stdio server
  • --args <args> — Arguments for the command
  • --url <url> — Endpoint of a streamable-http server
  • --env <var> — Env vars it needs set
  • --description <description>

handoff mcp remove

Forget a server you added.

handoff mcp remove [-h] server
  • <server> — Server name or id

handoff mcp enable

Offer a server's tools to agents again.

handoff mcp enable [-h] server
  • <server> — Server name or id

handoff mcp disable

Stop offering a server's tools to agents.

handoff mcp disable [-h] server
  • <server> — Server name or id

handoff skills

List, read, toggle or import skills.

handoff skills [-h] <action> ...

Subcommands: list, show, enable, disable, import

handoff skills list

Every skill in the workspace (the default).

handoff skills list [-h]

handoff skills show

A skill's description and body.

handoff skills show [-h] skill
  • <skill> — Skill id or name

handoff skills enable

Let agents load this skill.

handoff skills enable [-h] skill
  • <skill> — Skill id or name

handoff skills disable

Keep this skill out of every prompt.

handoff skills disable [-h] skill
  • <skill> — Skill id or name

handoff skills import

Import Markdown skill files, or a zip of them.

handoff skills import [-h] files [files ...]
  • <files>… — SKILL.md files or .zip bundles

handoff memory

Learned rules and remembered notes.

handoff memory [-h] <action> ...

Subcommands: rules, entries, add, forget

handoff memory rules

Rules learned from your decisions (the default).

handoff memory rules [-h]

handoff memory entries

Notes in the workspace's memory stores.

handoff memory entries [-h] [--store STORE]
  • --store <store> — Only this store (name or id)

handoff memory add

Remember a note in the workspace's long-term store.

handoff memory add [-h] [--key KEY] [--store STORE] text [text ...]
  • <text>…
  • --key <key> — A short label (default: the first words)
  • --store <store> — Store name or id (default: long-term)

handoff memory forget

Delete a rule or a note by id.

handoff memory forget [-h] entry_id
  • <entry_id> — A pref_… rule id or a ment_… entry id

handoff rules

List the rules it has learned from you.

handoff rules [-h]

handoff credentials

Connect, check or forget service credentials.

handoff credentials [-h] <action> ...

Subcommands: list, set, check, forget, gmail

handoff credentials list

Every provider and whether it is connected (the default).

handoff credentials list [-h]

handoff credentials set

Store a credential, read hidden from the terminal.

handoff credentials set [-h] [--from-env VAR] [--label LABEL] provider
  • <provider> — groq, anthropic, linear, slack, slack_webhook, github
  • --from-env <var> — Take the value from this variable
  • --label <label>

handoff credentials check

Verify stored credentials against the real services.

handoff credentials check [-h] [provider]
  • [<provider>]

handoff credentials forget

Delete a stored credential.

handoff credentials forget [-h] provider
  • <provider>

handoff credentials gmail

Sign in to Gmail in the browser (the MCP server's own OAuth).

handoff credentials gmail [-h]

handoff schedules

Cron schedules: list, switch on/off, fire one now.

handoff schedules [-h] <action> ...

Subcommands: list, toggle, run

handoff schedules list

Every schedule and when it next fires (the default).

handoff schedules list [-h]

handoff schedules toggle

Switch a schedule on or off.

handoff schedules toggle [-h] schedule_id
  • <schedule_id>

handoff schedules run

Fire a schedule's workflow now.

handoff schedules run [-h] [--watch] schedule_id
  • <schedule_id>
  • --watch — Follow the run's events live

handoff scheduler

Run the scheduler in the foreground until Ctrl-C.

handoff scheduler [-h]

handoff settings

Show or change the model chain and the confidence threshold.

handoff settings [-h] <action> ...

Subcommands: show, model, threshold

handoff settings show

The active configuration, secrets left out (the default).

handoff settings show [-h]

handoff settings model

Set the provider and model chain (written to .env).

handoff settings model [-h] provider primary [fallback]
  • <provider> — bedrock, groq or anthropic
  • <primary> — Model id the agents reason with
  • [<fallback>] — Cheaper model for high-volume steps

handoff settings threshold

Below this confidence the agent stops and asks you.

handoff settings threshold [-h] value
  • <value> — 0 to 1, e.g. 0.7

handoff usage

Tokens spent and what they cost, per model.

handoff usage [-h] [--days DAYS]
  • --days <days> — Only the last N days; default 30

handoff say

Speak a sentence through the configured voice.

handoff say [-h] [--out FILE] [--voice VOICE] text [text ...]
  • <text>…
  • --out <file> — Write the audio here instead of playing it
  • --voice <voice> — Voice id (default: the configured one)

handoff listen

Transcribe an audio file.

handoff listen [-h] file
  • <file> — A WAV (any engine) or another format Groq accepts

handoff talk

A spoken conversation: your microphone in, the voice out.

handoff talk [-h] [--mic] [--voice VOICE] [--new]
  • --mic — Record push-to-talk (needs sounddevice)
  • --voice <voice>
  • --new — Start a fresh chat

handoff workspace

Export or import a workspace.yml / bundle, switch the default.

handoff workspace [-h] <action> ...

Subcommands: list, export, import, remove, switch

handoff workspace list

List workspaces (the default).

handoff workspace list [-h]

handoff workspace export

Write workspace.yml (or a .zip bundle) to a path.

handoff workspace export [-h] [--workspace EXPORT_WORKSPACE] path
  • <path> — Where to write; .zip for a bundle, anything else for YAML
  • --workspace <export_workspace> — Workspace id (default: the selected or default workspace)

handoff workspace import

Create a workspace from a workspace.yml or bundle.

handoff workspace import [-h] path
  • <path>

handoff workspace remove

Delete a workspace and everything scoped to it.

handoff workspace remove [-h] workspace_id
  • <workspace_id>

handoff workspace switch

Make a workspace the default one every command acts on.

handoff workspace switch [-h] workspace_id
  • <workspace_id>

handoff serve

Start the web UI.

handoff serve [-h] [--port PORT] [--host HOST]
  • --port <port>
  • --host <host> — Bind address (0.0.0.0 to expose); default 127.0.0.1

handoff desktop

Open Handoff in a native window.

handoff desktop [-h] [--port PORT]
  • --port <port>

handoff share

Put a running handoff serve on a public trycloudflare URL.

handoff share [-h] [--port PORT]
  • --port <port> — The port handoff serve is on

handoff docs

List the guides, or open them in the running app.

handoff docs [-h] [--open] [--port PORT]
  • --open — Open /docs in the browser
  • --port <port>

handoff deploy

Publish the site, or the AgentCore runtime.

handoff deploy [-h] <command> ...
  • <target> — one of site, agentcore
  • <extra> — Passed through to the deploy script

handoff doctor

Check which credentials actually work.

handoff doctor [-h] [checks ...]
  • [<checks>] — Only run these (e.g. gmail linear slack)

handoff completion

Print a shell completion script.

handoff completion [-h] <command>
  • <shell> — one of bash, zsh, fish

handoff version

Print the version.

handoff version [-h]