CLI Reference

Complete reference for the agentoven command-line interface — 55+ commands across 13 command groups.

The agentoven CLI is your primary interface for managing agents, providers, tools, prompts, recipes, sessions, and kitchens from the terminal.

Installation

bash

# From crates.io (recommended)
cargo install agentoven-cli

# From source
git clone https://github.com/agentoven/agentoven.git
cd agentoven
cargo install --path crates/agentoven-cli

# macOS (Homebrew)
brew install agentoven/tap/agentoven

Global Flags

Every command accepts these flags:

Flag	Env Var	Default	Description
`--url <url>`	`AGENTOVEN_URL`	`http://localhost:8080`	Control plane URL
`--api-key <key>`	`AGENTOVEN_API_KEY`	—	API key for authentication
`-k, --kitchen <name>`	`AGENTOVEN_KITCHEN`	`default`	Kitchen (workspace) scope
`--output <fmt>`	—	`text`	Output format: `text`, `json`, `table`
`--help`	—	—	Show help for any command

Commands at a Glance

Group	Commands	Description
`init`	—	Initialize a new AgentOven project
`apply`	—	Declarative resource management from YAML/JSON/TOML manifests
`agent`	15 subcommands	Full agent lifecycle management
`provider`	7 subcommands	Model provider management
`tool`	5 subcommands	MCP tool management
`prompt`	7 subcommands	Versioned prompt templates
`recipe`	7 subcommands	Multi-agent workflows
`session`	6 subcommands	Multi-turn chat sessions
`kitchen`	4 subcommands	Workspace/tenant management
`trace`	4 subcommands	Observability and cost tracking
`rag`	2 subcommands	RAG pipeline operations
`dashboard`	—	Start control plane + dashboard UI
`login`	—	Authenticate with the control plane
`status`	—	Show control plane health

`agentoven init`

Initialize a new AgentOven project in the current directory.

bash

agentoven init [path] [--name <name>] [--framework <fw>]

Flag	Default	Description
`path`	`.`	Project directory
`--name, -n`	directory name	Agent name
`--framework, -f`	`custom`	Framework: `langgraph`, `crewai`, `openai-sdk`, `autogen`, `managed`, `custom`

Creates agentoven.toml, prompts/system.md, and .gitignore.

bash

agentoven init my-agent --framework openai-sdk

`agentoven apply`

Declarative resource management — apply agents, recipes, and tools from YAML/JSON/TOML manifest files. Supports multi-document YAML with --- separators.

Use this when the source of truth is a manifest file.

bash

agentoven apply -f <manifest-file> [--dry-run]

Flag	Description
`-f, --file`	Path to manifest file (YAML, JSON, or TOML)
`--dry-run`	Preview changes without applying

Manifest Format

Each document in a manifest requires a kind field: Agent, Recipe, or ToolSet.

yaml

# agent.yaml — multi-document manifest
kind: Agent
name: summarizer
description: "Summarizes documents with citations"
model_provider: openai
model_name: gpt-4o
system_prompt: "You are a document summarizer."
tags:
  - production
ingredients:
  models:
    - name: gpt-4o
      provider: openai
      role: primary
  tools:
    - name: web-search
      protocol: mcp
---
kind: ToolSet
tools:
  - name: web-search
    description: "Search the web for information"
    endpoint: https://tools.example.com/search
    transport: http
  - name: calculator
    description: "Perform math calculations"
    endpoint: https://tools.example.com/calc
---
kind: Recipe
name: doc-review
steps:
  - name: summarize
    agent: summarizer
    kind: agent
  - name: review-gate
    kind: human-gate
    depends_on:
      - summarize
  - name: publish
    agent: publisher
    kind: agent
    depends_on:
      - review-gate

bash

# Apply all resources from a manifest
agentoven apply -f agent.yaml

# Preview without applying
agentoven apply -f agent.yaml --dry-run

For workflow definitions, use YAML when you want declarative manifests and Python when the workflow is code-first.

`agentoven agent`

Full agent lifecycle management — register, deploy, test, and retire agents.

Agent Lifecycle

text

  register → bake → ready
                ↓       ↑
              cool → rewarm
                ↓
             retire

`agent register`

bash

agentoven agent register <name> [flags]
# or from config file:
agentoven agent register --config agentoven.toml
# or from a YAML/JSON/TOML definition:
agentoven agent register --from agent.yaml

Flag	Description
`--description`	Agent description
`--framework`	Framework: `langgraph`, `crewai`, `openai-sdk`, `autogen`, `managed`, `custom`
`--mode`	Agent mode: `managed` or `external` (A2A proxy). Default: `managed`
`--model-provider`	Primary model provider name
`--model-name`	Primary model name
`--backup-provider`	Backup provider for failover
`--backup-model`	Backup model for failover
`--system-prompt`	System prompt / instructions
`--max-turns`	Maximum turns for managed agentic loop
`--skill`	Agent skills (repeatable)
`--tag`	Tags (repeatable)
`--a2a-endpoint`	A2A endpoint for external agents
`--guardrail`	Guardrail in `kind:stage` format (repeatable)
`--config, -c`	Path to `agentoven.toml`
`--from, -f`	Path to agent definition file (YAML/JSON/TOML)

bash

agentoven agent register summarizer \
  --description "Summarizes documents with citations" \
  --framework managed \
  --model-provider my-openai \
  --model-name gpt-4o \
  --system-prompt "You are a document summarizer." \
  --skill summarization \
  --tag production

`agent list`

bash

agentoven agent list [--tag <tag>] [--status <status>]

`agent get`

bash

agentoven agent get <name>
# Supports version pinning:
agentoven agent get [email protected]

`agent update`

bash

agentoven agent update <name> [--description <text>] [--model-provider <p>] [--model-name <m>] [--system-prompt <s>] [--max-turns <n>] [--json <raw>]

`agent delete`

bash

agentoven agent delete <name> [--force]

`agent bake`

Deploy (bake) an agent — resolves all ingredients, validates configuration, and sets the agent to ready.

bash

agentoven agent bake <name>

`agent recook`

Hot-swap agent configuration without full redeployment (edit modal re-cook).

bash

agentoven agent recook <name> [--model-provider <p>] [--model-name <m>] [--system-prompt <s>] [--max-turns <n>] [--json <raw>]

`agent cool`

Pause (cool) a deployed agent. Stops processing but keeps registration.

bash

agentoven agent cool <name>

`agent rewarm`

Bring a cooled agent back to ready state.

bash

agentoven agent rewarm <name>

`agent retire`

Permanently decommission an agent.

bash

agentoven agent retire <name>

`agent test`

Test an agent — one-shot or interactive playground.

bash

agentoven agent test <name> [--message <msg>] [--interactive] [--thinking]

Flag	Description
`--message, -m`	One-shot message to send
`--interactive, -i`	Interactive REPL mode
`--thinking`	Enable chain-of-thought / thinking blocks

`agent invoke`

Invoke a managed agent with a full agentic loop and execution trace.

bash

agentoven agent invoke <name> --message <msg> [--thinking]

`agent config`

Show the resolved configuration for a baked agent (all ingredients resolved).

bash

agentoven agent config <name>

`agent card`

Show the A2A Agent Card (discovery metadata).

bash

agentoven agent card <name>

`agent versions`

List version history for an agent.

bash

agentoven agent versions <name>

`agentoven provider`

Manage model providers — OpenAI, Anthropic, Azure OpenAI, Ollama, LiteLLM.

`provider list`

bash

agentoven provider list

`provider add`

bash

agentoven provider add <name> --kind <kind> [--api-key <key>] [--base-url <url>] [--model <model>]

Flag	Description
`--kind, -k`	Provider kind: `openai`, `azure-openai`, `anthropic`, `ollama`, `litellm`
`--api-key`	API key (or set via environment)
`--base-url`	Base URL / endpoint
`--model`	Default model name

bash

agentoven provider add my-openai --kind openai --api-key $OPENAI_API_KEY --model gpt-4o
agentoven provider add local-llm --kind ollama --base-url http://localhost:11434 --model llama3

`provider get`

bash

agentoven provider get <name>

`provider update`

bash

agentoven provider update <name> [--api-key <key>] [--base-url <url>] [--model <model>] [--enabled true|false]

`provider remove`

bash

agentoven provider remove <name> [--force]

`provider test`

Test provider connectivity and credentials.

bash

agentoven provider test <name>

`provider discover`

Discover models available from a provider.

bash

agentoven provider discover <name>

`agentoven tool`

Manage MCP (Model Context Protocol) tools.

Command	Description
`tool list`	List all registered MCP tools
`tool add <name>`	Add a tool (`--description`, `--schema`, `--schema-file`)
`tool get <name>`	Get tool details and input schema
`tool update <name>`	Update description or schema
`tool remove <name>`	Remove a tool (`--force`)

bash

agentoven tool add web-search \
  --description "Search the web" \
  --schema '{"type":"object","properties":{"query":{"type":"string"}}}'

`agentoven prompt`

Manage versioned prompt templates with variable interpolation.

Command	Description
`prompt list`	List all prompt templates
`prompt add <name>`	Add a prompt (`--template` or `--from-file`, `--variables`)
`prompt get <name>`	Get prompt template and metadata
`prompt update <name>`	Update template text (creates a new version)
`prompt remove <name>`	Remove a prompt (`--force`)
`prompt validate <name>`	Validate a prompt template
`prompt versions <name>`	List version history

bash

agentoven prompt add summarizer-system \
  --template "You are a {role}. Summarize the following in {format} format." \
  --variables "role,format"

`agentoven recipe`

Manage multi-agent workflows (recipes) — DAG-based orchestration with human gates.

Command	Description
`recipe create <name>`	Create a recipe (`--from` YAML/TOML file)
`recipe list`	List all recipes
`recipe get <name>`	Get recipe details and steps
`recipe delete <name>`	Delete a recipe (`--force`)
`recipe bake <name>`	Execute a recipe (`--input` JSON or `--input-file`)
`recipe runs <name>`	Show execution history (`--limit`)
`recipe approve <name>`	Approve/reject a human gate (`--run-id`, `--gate-id`, `--approved`, `--comment`)

bash

# Create and execute a recipe
agentoven recipe create doc-review --from recipe.yaml
agentoven recipe bake doc-review --input '{"document_url":"https://..."}'

# Approve a human gate
agentoven recipe approve doc-review \
  --run-id abc123 --gate-id gate-1 --approved true --comment "LGTM"

`agentoven session`

Manage multi-turn chat sessions with history and thinking mode.

Command	Description
`session list <agent>`	List sessions for an agent
`session create <agent>`	Create a new session
`session get <agent> <session-id>`	Get session details and message history
`session delete <agent> <session-id>`	Delete a session (`--force`)
`session send <agent> <session-id>`	Send a message (`--message`, `--thinking`)
`session chat <agent> [session-id]`	Interactive chat REPL (`--thinking`)

bash

# Create a session and start chatting
agentoven session create my-agent
agentoven session chat my-agent <session-id> --thinking

# Or auto-create a new session
agentoven session chat my-agent --thinking

`agentoven kitchen`

Manage kitchens (workspaces/tenants) — view plans, limits, and settings.

Command	Description
`kitchen list`	List all kitchens
`kitchen get <id>`	Get kitchen details and plan limits
`kitchen settings`	View current kitchen settings
`kitchen update-settings`	Update settings (`--trace-ttl`, `--audit-ttl`, `--max-items`, `--archive`, `--json`)

bash

agentoven kitchen settings
agentoven kitchen update-settings --trace-ttl 30d --archive true

`agentoven trace`

Inspect traces, cost data, and audit logs.

Command	Description
`trace ls`	List recent traces (`--agent`, `--limit`)
`trace get <trace-id>`	Inspect a specific trace with span details
`trace cost`	Show cost summary (`--range 24h/7d/30d`, `--group-by agent/model/kitchen`)
`trace audit`	Show audit log (`--limit`)

bash

agentoven trace ls --agent summarizer --limit 50
agentoven trace cost --range 7d --group-by model
agentoven trace audit --limit 100

`agentoven rag`

RAG (Retrieval-Augmented Generation) pipeline operations.

`rag query`

bash

agentoven rag query "<text>" [--strategy <s>] [--top-k <n>] [--sources]

Flag	Default	Description
`--strategy`	`naive`	Strategy: `naive`, `sentence-window`, `parent-doc`, `hyde`, `agentic`
`--top-k`	`5`	Max results to return
`--sources`	`false`	Include source documents in output

`rag ingest`

bash

agentoven rag ingest <path> [--chunk-size <n>] [--chunk-overlap <n>] [--collection <name>]

Flag	Default	Description
`--chunk-size`	`1000`	Chunk size in characters
`--chunk-overlap`	`200`	Overlap between chunks
`--collection`	`default`	Target collection/index name

bash

agentoven rag ingest ./knowledge-base/ --collection product-docs --chunk-size 800
agentoven rag query "How does billing work?" --strategy hyde --sources

`agentoven dashboard`

Start the control plane and open the dashboard UI.

bash

agentoven dashboard [--port <port>] [--no-open] [--server-bin <path>]

Flag	Default	Description
`--port, -p`	`8080`	Port for the control plane server
`--no-open`	`false`	Don't open the browser automatically
`--server-bin`	auto-detect	Path to control plane binary (env: `AGENTOVEN_SERVER_BIN`)

`agentoven login`

Authenticate with the control plane and save credentials to ~/.agentoven/config.toml.

bash

agentoven login [--api-key <key>] [--url <url>]

`agentoven status`

Show control plane connection status, agent count, and CLI version.

bash

agentoven status

Configuration File

agentoven init creates an agentoven.toml:

toml

[agent]
name = "my-agent"
version = "0.1.0"
description = ""
framework = "custom"

[ingredients]
# [[ingredients.models]]
# name = "gpt-4o"
# provider = "azure-openai"

[bake]
# environment = "production"

[oven]
# url = "http://localhost:8080"
# kitchen = "default"

Environment Variables

Variable	Description
`AGENTOVEN_URL`	Control plane URL
`AGENTOVEN_API_KEY`	API key for authentication
`AGENTOVEN_KITCHEN`	Default kitchen scope
`AGENTOVEN_SERVER_BIN`	Path to control plane binary
`AGENTOVEN_CORS_ORIGINS`	Allowed CORS origins (comma-separated)
`AGENTOVEN_REQUIRE_AUTH`	Require auth for all endpoints (`true`/`false`)
`AGENTOVEN_SA_SECRET`	HMAC secret for service account tokens