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, start the server, or push agents to Distri Cloud.

Installation​

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

Verify your installation:

distri --version

Commands Overview​

distri -h
Usage: distri [OPTIONS] [COMMAND]

Commands:
  list               List available agents
  list-tools         List available tools
  run                Run agent in interactive chat mode or execute a single task
  serve              Start the server (API only by default, use --ui to enable web interface)
  push               Push agent definitions to Distri Cloud
  toolcall           Call a specific tool directly
  publish            Publish a plugin to the DAP registry
  validate-prompt    Validate custom agent prompt templates
  generate-prompt    Generate and print the planning prompt for an agent
  generate-response  Generate and stream the LLM response with parsed tool calls
  help               Print this message or the help of the given subcommand(s)

Options:
  -c, --config <CONFIG>  Path to the distri.toml configuration file
  -v, --verbose          Verbose output
      --agent <AGENT>    Agent name to use (defaults to 'distri')
      --input <INPUT>    Input data as JSON string or text
  -h, --help             Print help
  -V, --version          Print version

Running Agents​

Interactive chat mode​

distri run my_agent

Opens an interactive terminal session where you can chat with your agent.

Single task execution​

distri run my_agent --task "your task here"

Runs the agent with a single task and exits when complete.

Example​

distri run search_agent --task "who is the prime minister of singapore"
⏺ Thought for 2.2 seconds

⏺ search({  "query": "current prime minister of Singapore",  "limit": 1})
⏺ Thought for 1.3 seconds

⏺ final({  "input": "The current Prime Minister of Singapore is Lawrence Wong."})
The current Prime Minister of Singapore is Lawrence Wong.

Starting the Server​

The distri serve command starts the Distri server, which exposes REST and WebSocket APIs for agent invocation.

distri serve --project ./agents --port 8787
OptionDescription
--project <PATH>Path to the directory containing agent definitions
--port <PORT>Port to run on (default: 8787)
--uiEnable the web interface

Agents are automatically discovered from the project directory — any .md files with valid agent TOML frontmatter are registered.

Managing Agents on Distri Cloud​

Login​

distri login

Authenticates with Distri Cloud and stores your credentials locally.

Push agents​

# Push all agents in the project
distri push

# Push a specific agent
distri push agents/my_agent.md

After pushing, your agent appears in the dashboard and is immediately available via API.

List agents​

distri list

Lists all agents registered locally or on the connected server.

Tools​

List available tools​

distri list-tools

Shows all tools available to the current agent, including built-in, external, and MCP tools.

Call a tool directly​

distri toolcall tool_name '{"param": "value"}'

Invokes a specific tool without running the full agent loop. Useful for testing tool implementations.

Prompt Development​

Validate prompt templates​

distri validate-prompt

Checks agent prompt templates for Handlebars syntax errors and missing variables.

Generate prompt preview​

distri generate-prompt --agent my_agent --task "test task"

Generates and prints the full planning prompt that would be sent to the LLM, with all template variables resolved.

Stream raw LLM response​

distri generate-response --agent my_agent --task "test task"

Streams the raw LLM response with parsed tool calls, without executing the full agent loop. Useful for debugging prompt behavior.

Publishing Plugins​

distri publish

Publishes a plugin to the DAP (Distri Agent Plugin) registry, making it available for other agents to use.

Configuration​

The CLI reads configuration from distri.toml in the project root. Override the config path with --config:

distri serve --config ./custom-config.toml

Use --verbose for detailed logging output:

distri run my_agent --task "debug this" --verbose