CLI reference

The cradle CLI — a thin HTTP client for cradle-server, its config, and the full command catalogue.

The cradle CLI is a thin HTTP client that talks to cradle-server. It never touches the database directly and never loads model runners — every command is an HTTP call against the admin API.

cradle <subcommand>

Config file

Configuration lives in ~/.cradle/cli-config.json (override the location with $CRADLE_CONFIG_DIR):

{
  "servers": {
    "default":    { "url": "http://127.0.0.1:31416", "apiKey": "ck_live_…" },
    "production": { "url": "https://cradle.company.local", "apiKey": "ck_live_…" }
  },
  "currentServer": "default",
  "currentProject": "personal"
}

cradle login --url <url> --key <key> [--name <profile>] writes a server, sets it current, and probes /admin/health to verify. cradle servers list / use / remove switches profiles.

Every request carries X-Cradle-Project: <currentProject> from the config. cradle projects use <slug> updates that header locally. Admin keys can override the binding; scoped keys must use the project they are bound to (the server returns 403 on mismatch).

Output modes

--json turns every command into a clean JSON stream suitable for jq:

cradle agents execute <id> --text "ping" --json | jq '.replies[0].text'
cradle keys list --json | jq '.[] | select(.scopes | contains(["admin:*"]))'
cradle models list --json | jq '.system.totalRamGb'

Without --json, output is a coloured, aligned text table.

Command catalogue

cradle init               # save config + verify health
cradle login              # save server credentials
cradle servers            # list / use / remove

cradle server init        # bootstrap a headless cradle-server (systemd, operator-driven)
cradle server package     # build a deployable zip for a target Linux host

cradle remote show        # remote GPU node config and operator commands
cradle remote set         # configure a remote GPU node (no SSH push)
cradle remote pool probe  # probe all pool nodes for health
cradle remote pool plan   # autoscaler plan (operator-driven, no execution)

cradle tenants list              # single-host tenant registry
cradle tenants create <id>       # bootstrap a new tenant instance
cradle tenants start <id>        # systemctl start cradle-server-<id>
cradle tenants stop <id>         # systemctl stop cradle-server-<id>
cradle tenants credentials <id>  # show client-credentials.json for a tenant

cradle health             # probe /admin/health

cradle projects list      # all projects on the server
cradle projects create <slug> [--name --description]
cradle projects use <slug>                   # local — sends X-Cradle-Project next call

cradle agents list                           # filtered by current project
cradle agents show <id>
cradle agents execute <id> --text "…"        # one-shot, returns {replies:[…]}
cradle agents create --template <slug>       # uses built-in agent templates

cradle kb list                               # knowledge bases in the current project

cradle models list                           # catalog + installed + compat verdict
cradle models list --recommended             # OpenLLM leaderboard top picks
cradle models check <catalogId>              # hardware verdict for one model
cradle models pull <catalogId>               # SSE-streamed download

cradle keys list                             # all api keys (no plaintext)
cradle keys create --name … --scopes a:b,c:d --project <id>   # plaintext shown ONCE
cradle keys revoke <id>                       # soft delete

cradle tickets list [--status pending]
cradle tickets show <id>

cradle channels list                          # filtered by current project

cradle completion bash                        # shell completion script

Write commands refuse gracefully when a server endpoint is not implemented yet: they print not implemented … (Phase N+) and exit with code 2 — never a silent no-op.

Server bootstrap (`cradle server init`)

This is the operator-driven way to deploy a headless cradle-server on a remote machine (jump host / closed contour). The CLI never pushes over SSH; the operator runs it on the target server.

# on the target server, as root:
cradle server init \
  --data-dir /var/lib/cradle/tenant-a \
  --port 31416 \
  --bind 0.0.0.0 \
  --service-name cradle-server-tenant-a

It creates the data directory, bootstraps the SQLite DB and first admin:* key, writes and enables a systemd unit, waits for /admin/health, and writes client-credentials.json (mode 0600) into the data directory. Running it again on the same data directory is idempotent.

Key flags

Flag	Default	Purpose
`--data-dir`	`/var/lib/cradle`	SQLite DB, models, credentials file
`--port`	`31416`	HTTP API port
`--bind`	`0.0.0.0`	Bind host (`127.0.0.1` for local-only)
`--user`	`cradle`	OS user for the systemd service
`--service-name`	`cradle-server`	systemd unit name
`--skip-systemd`	`false`	Only bootstrap the DB, no service
`--dry-run`	`false`	Print the plan without touching the system
`--scopes`	`admin:*`	Scopes for the generated client key

Dev / non-systemd mode

cradle server init --data-dir /tmp/cradle-test --skip-systemd

This bootstraps the DB and writes the bootstrap admin key to client-credentials.json without starting a service. Start the server manually with cradle-server --data-dir /tmp/cradle-test.

Remote GPU (`cradle remote`)

Configure a remote llama.cpp / vLLM node without pushing commands from the client. cradle remote set only stores configuration; the actual SSH commands are printed for the operator to run on the jump host.

cradle remote set \
  --host gpu-1.local --user cradle \
  --ssh-key-path /root/.ssh/gpu-1 \
  --remote-port 8080 --model-path /models/qwen3-8b.gguf

cradle remote show

For multiple nodes, cradle remote pool probe health-checks every node and cradle remote pool plan prints a scale-up / scale-down plan with the operator commands to run. The autoscaler never executes SSH or cloud API calls itself.

Bash completion

cradle completion bash > /usr/local/etc/bash_completion.d/cradle
# or per-user:
cradle completion bash >> ~/.bashrc

The completion script covers top-level commands and one level of subcommands.