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:
| Flag | Description |
|---|---|
--verbose | Enable INFO-level log output (default: WARN) |
--debug | Enable 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 / Env | Level | Output |
|---|---|---|
| (none) | WARN | Warnings and errors only |
--verbose | INFO | Informational messages + above |
--debug or KDEPS_DEBUG=true | DEBUG | Debug 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
| Command | Page | Description |
|---|---|---|
kdeps run | Dev commands | Run a workflow locally |
kdeps [path] | Dev commands | Run path or ./workflow.yaml, as kdeps run |
kdeps validate | Dev commands | Validate workflow config |
kdeps test | Dev commands | Run the workflow's evals: in-process, no port bound |
kdeps new | Dev commands | Scaffold a new agent |
kdeps edit | Dev commands | Edit global config |
kdeps doctor | Dev commands | System health checks |
kdeps instrument | Dev commands | List, show and remove sessions recorded with --instrument |
kdeps --upgrade | Dev commands | Check for and install a newer kdeps release |
kdeps install/update/uninstall <asset> | Dev commands | Install, update or remove harness, tool definitions, recipes, model registries and templates; kdeps list <shelf> filters by shelf; kdeps profile picks what is installed |
kdeps llamafile | Dev commands | Llamafile model registry (list, update) |
kdeps knowledge | Dev commands | Knowledge vault: init, build, check, recall, report |
kdeps install/search/info/submit/verify | Registry commands | Search, install, publish packages (and the assets above) |
kdeps bundle package | Packaging commands | Package for distribution |
kdeps bundle build | Packaging commands | Build Docker image |
kdeps export iso | Packaging commands | Export bootable image |
kdeps export k8s | Packaging commands | Generate Kubernetes manifests |
kdeps llm | LLM commands | LLM 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:latestProduction 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.0Kubernetes 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-agentExit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | General error |
2 | Validation error |
3 | Execution error |
Environment variables
| Variable | Description |
|---|---|
KDEPS_DEBUG | Set true to enable debug logging (equivalent to --debug) |
KDEPS_LOG_FORMAT | Set json for structured JSON log output |
KDEPS_EDITOR | Editor for kdeps edit (overrides VISUAL/EDITOR) |
KDEPS_PYTHON_VERSION | Global Python version (e.g., 3.12) |
KDEPS_OFFLINE_MODE | Set true to block all external LLM calls |
KDEPS_LLM_OVERRIDE_URL | An 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_MODE | Set 1, true, or yes to restrict tool surface (no bash, no network) |
KDEPS_AGENT_PRESET | audit, explain, or implement - combines lean mode with permission mode |
KDEPS_PERMISSION_MODE | read-only, workspace-write, or danger-full-access |
OLLAMA_HOST | Ollama server URL |
TZ | Timezone applied to all workflow runs |
KDEPS_CHAT_TIMEOUT | Default 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_TIMEOUT | Default timeout for HTTP requests |
KDEPS_PYTHON_TIMEOUT | Default timeout for Python resources |
KDEPS_EXEC_TIMEOUT | Default timeout for the exec component |
KDEPS_SQL_TIMEOUT | Default timeout for SQL resources |
KDEPS_ON_ERROR_ACTION | Default error action: fail, continue, retry |
KDEPS_ON_ERROR_MAX_RETRIES | Default max retries for retry action |
KDEPS_ON_ERROR_RETRY_DELAY | Default delay between retries |
KDEPS_ASSETS_URL | Where kdeps update downloads from (a mirror laid out like assets/ in kdeps/packages); off disables asset downloads |
KDEPS_ASSETS_DIR | Where downloaded assets and lock.json live (default ~/.kdeps/assets) |
KDEPS_ASSETS_SRC | A 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_PROFILE | Install 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
--devflag for hot reload during development - Use
--debugflag to troubleshoot issues - Validate frequently with
kdeps validate - Always validate before you package:
kdeps validate workflow.yaml - Use
--gpu cudafor GPU workloads - Tag images with version numbers:
--tag my-agent:v1.0.0
See also
- Dev commands - run, validate, new, edit, doctor, instrument, chat
- Registry commands - search, install, publish
- Packaging commands - bundle, export, build
- Installation
