Skip to main content

CLI Reference

The distri CLI is the primary tool for developing, testing, and deploying agents. Install it to run agents locally, manage skills, inspect traces, or push your work to Distri Cloud.

Installation​

curl -fsSL https://distri.dev/install.sh | sh
distri --version

Global flags: -v/--verbose, --base-url URL (override the server, otherwise DISTRI_BASE_URL), --config PATH (path to distri.toml).

Agent execution​

Interactive TUI​

distri                                   # default agent
distri tui my_agent                      # a specific agent
distri tui my_agent --resume last        # resume ("last" or a thread id)
distri tui my_agent --overrides '{"model":"gpt-4.1"}'

Single task​

distri run --task "summarize this quarter's metrics" --agent my_agent
OptionDescription
--task "..."The task to execute (required)
--agent NAMEAgent name (defaults to distri_runner)
--remoteRun in a remote browsr sandbox
--resume IDResume an existing thread (last for most recent)
--context JSON{"envs":{...},"secrets":{...}} available to tools
--overrides JSONOverride agent config fields
--task-id ID / --thread-id IDAssign specific ids
--tag KEY=VALUETag the run's traces/thread (repeatable)
--header KEY=VALUEExtra HTTP header (repeatable)
--traceparent HEADERW3C traceparent for distributed tracing

Deploy, push & checkout​

distri push is the primary deploy: it syncs the whole agents/, skills/, templates/ tree to your workspace. distri checkout pulls it back.

distri push                              # sync agents/ skills/ templates/ from cwd
distri push skills/my-skill              # push a single item
distri push --dry-run                    # preview without uploading

distri checkout                          # pull the workspace into the local layout
distri checkout --out ./ws --scope skills --force

Agents​

distri agents list
distri agents push agents/my_agent.md
distri agents push agents/ --all         # --all required for a directory
distri agents delete my_agent            # confirm prompt
distri agents delete my_agent -y         # skip confirmation

Skills​

Skills are reusable capability packages (a SKILL.md per folder).

distri skills list
distri skills list --all                 # include public/system skills
distri skills push skills/my-skill
distri skills push skills/ --all

Skill registries​

distri search "pdf"                      # search configured registries
distri install pdf-processing@anthropic  # <name>@<registry>
distri registry list
distri registry add myreg --kind github https://github.com/org/skills
distri registry remove myreg

Prompt templates​

Prompt templates are Handlebars (.hbs) files under templates/.

distri prompts list
distri prompts push templates/system.hbs

Traces & debugging​

distri traces list                       # recent (default 20)
distri traces list --limit 50
distri traces list --agent scoring_agent
distri traces list --tag team=growth     # repeatable
distri traces show <id>                  # Gantt tree (trace / span / thread id)
distri traces show --latest
distri traces show <id> --span "llm"
distri traces show <id> -v               # span ids + input/output summaries
distri traces export --latest            # export a replay fixture (JSON)

Tools​

distri tools list
distri tools list --filter "search"
distri tools list --agent my_agent
distri tools invoke my_tool --input '{"query":"test"}'
distri tools invoke my_tool --input '{"query":"test"}' --session <session-id>

Threads​

distri threads list

Providers & models​

distri providers list
distri providers set openai --secret OPENAI_API_KEY=sk-... --default-model openai/gpt-4.1-mini
distri providers delete openai

distri models list
distri models get-default
distri models set-default openai/gpt-4.1-mini

Secrets & connections​

distri secrets list
distri secrets set MY_API_KEY sk-abc123
distri secrets delete MY_API_KEY

distri connections list
distri connections token <connection-id>

Auth & profiles​

distri login                             # interactive
distri login --email [email protected]
distri login --skip-workspace
distri login --profile staging

distri profile list
distri profile use staging
distri profile show [name]
distri profile delete staging [-y]
distri profile config set --api-key <key> --workspace-id <id> --api-url <url>
distri profile config unset --api-key

Server & maintenance​

distri serve                             # local server on :7777 (opens the web UI)
distri serve --host 0.0.0.0 --port 9000
distri serve --headless                  # don't open the web UI
distri serve --no-ui                     # don't serve the UI bundle

distri update [--pre]                    # pull latest distri-server + UI
distri version                           # installed cli/server/ui versions
distri uninstall                         # wipe ~/.distri/{bin,ui,cache}
Workflows

There is no distri workflows command. Workflows run through the runtime and the @distri/core WorkflowRunner (with useWorkflow / useWorkflowRunner in React), not the CLI.