Skip to content

CLI reference ​

The kdeps CLI creates, runs, tests, packages, and deploys agents. All commands follow kdeps [command] [options].

Global flags ​

All commands support these global flags:

FlagDescription
--verboseEnable INFO-level log output (default: WARN)
--debugEnable DEBUG-level log output with source locations
--instrument[=<name>]Record the run as a named session in ~/.kdeps/instrument/<name>/ (prompts, model and tool calls, workflow events, every log line) for a model to debug; bare --instrument names it by time. See Record a session and kdeps instrument

Structured logging ​

kdeps uses structured JSON logs through the Go package log/slog. Warnings and errors go to stderr in human-readable format by default.

Flag / EnvLevelOutput
(none)WARNWarnings and errors only
--verboseINFOInformational messages + above
--debug or KDEPS_DEBUG=trueDEBUGDebug details + above
KDEPS_LOG_FORMAT=json(any)Structured JSON output on stderr

JSON format:

bash
export KDEPS_LOG_FORMAT=json
kdeps run workflow.yaml
# Output: {"time":"...","level":"WARN","msg":"experimental software",...}

Commands ​

CommandPageDescription
kdeps runDev commandsRun a workflow locally
kdeps [path]Dev commandsRun path or ./workflow.yaml, as kdeps run
kdeps validateDev commandsValidate workflow config
kdeps testDev commandsRun the workflow's evals: in-process, no port bound
kdeps newDev commandsScaffold a new agent
kdeps editDev commandsEdit global config
kdeps doctorDev commandsSystem health checks
kdeps instrumentDev commandsList, show and remove sessions recorded with --instrument
kdeps --upgradeDev commandsCheck for and install a newer kdeps release
kdeps install/update/uninstall <asset>Dev commandsInstall, update or remove harness, tool definitions, recipes, model registries and templates; kdeps list <shelf> filters by shelf; kdeps profile picks what is installed
kdeps llamafileDev commandsLlamafile model registry (list, update)
kdeps knowledgeDev commandsKnowledge vault: init, build, check, recall, report
kdeps install/search/info/submit/verifyRegistry commandsSearch, install, publish packages (and the assets above)
kdeps bundle packagePackaging commandsPackage for distribution
kdeps bundle buildPackaging commandsBuild Docker image
kdeps export isoPackaging commandsExport bootable image
kdeps export k8sPackaging commandsGenerate Kubernetes manifests
kdeps llmLLM commandsLLM server appliances

Command workflow ​

Typical development flow ​

bash
# 1. Create new agent
kdeps new my-agent

# 2. Validate configuration
cd my-agent
kdeps validate workflow.yaml

# 3. Run the workflow's tests in-process
kdeps test .

# 4. Run locally with hot reload
kdeps run workflow.yaml --dev

# 5. Package for deployment
kdeps bundle package . --output dist/

# 6. Build Docker image (optional)
kdeps bundle build dist/my-agent-1.0.0.kdeps --tag my-agent:latest

Production deployment flow ​

bash
# 1. Validate before packaging
kdeps validate workflow.yaml

# 2. Run the workflow's tests
kdeps test .

# 3. Package workflow
kdeps bundle package . --output dist/

# 4. Build Docker image
kdeps bundle build dist/my-agent-1.0.0.kdeps \
  --tag registry.com/my-agent:v1.0.0 \
  --gpu cuda

# 5. Push to registry
docker push registry.com/my-agent:v1.0.0

Kubernetes deployment flow ​

bash
# 1. Build Docker image
kdeps bundle build . --tag registry.com/my-agent:v1.0.0
docker push registry.com/my-agent:v1.0.0

# 2. Generate Kubernetes manifests
kdeps export k8s . \
  --image registry.com/my-agent:v1.0.0 \
  --output k8s.yaml

# 3. Deploy to cluster
kubectl apply -f k8s.yaml
kubectl rollout status deployment/my-agent

Exit codes ​

CodeMeaning
0Success
1General error
2Validation error
3Execution error

Environment variables ​

VariableDescription
KDEPS_DEBUGSet true to enable debug logging (equivalent to --debug)
KDEPS_LOG_FORMATSet json for structured JSON log output
KDEPS_EDITOREditor for kdeps edit (overrides VISUAL/EDITOR)
KDEPS_PYTHON_VERSIONGlobal Python version (e.g., 3.12)
KDEPS_OFFLINE_MODESet true to block all external LLM calls
KDEPS_LLM_OVERRIDE_URLAn OpenAI-compatible endpoint that gets all model calls from workflow chat resources and agent sessions, for all backends and models. kdeps does not download or start a local model, and you do not need an API key. Use it to test workflows and agents against a stub or mock server (CI, offline)
KDEPS_LEAN_MODESet 1, true, or yes to restrict tool surface (no bash, no network)
KDEPS_AGENT_PRESETaudit, explain, or implement - combines lean mode with permission mode
KDEPS_PERMISSION_MODEread-only, workspace-write, or danger-full-access
OLLAMA_HOSTOllama server URL
TZTimezone applied to all workflow runs
KDEPS_CHAT_TIMEOUTDefault timeout for LLM chat resources. Agent-loop internal calls (compaction, judging) use a 10m default instead, and this variable caps them when set
KDEPS_HTTP_TIMEOUTDefault timeout for HTTP requests
KDEPS_PYTHON_TIMEOUTDefault timeout for Python resources
KDEPS_EXEC_TIMEOUTDefault timeout for the exec component
KDEPS_SQL_TIMEOUTDefault timeout for SQL resources
KDEPS_ON_ERROR_ACTIONDefault error action: fail, continue, retry
KDEPS_ON_ERROR_MAX_RETRIESDefault max retries for retry action
KDEPS_ON_ERROR_RETRY_DELAYDefault delay between retries
KDEPS_ASSETS_URLWhere kdeps update downloads from (a mirror laid out like assets/ in kdeps/packages); off disables asset downloads
KDEPS_ASSETS_DIRWhere downloaded assets and lock.json live (default ~/.kdeps/assets)
KDEPS_ASSETS_SRCA directory laid out like assets/ in the kdeps repo, loaded under the store; to develop assets. Set empty to turn off the automatic checkout fallback
KDEPS_PROFILEInstall profile for a first run without a terminal: minimum, workflows, agent, deploy, full, or a comma-separated list of sets and set/name items; unset installs only the sets the command loads

Tips ​

  • Use --dev flag for hot reload during development
  • Use --debug flag to troubleshoot issues
  • Validate frequently with kdeps validate
  • Always validate before you package: kdeps validate workflow.yaml
  • Use --gpu cuda for GPU workloads
  • Tag images with version numbers: --tag my-agent:v1.0.0

See also ​

kdeps has the Apache 2.0 License.