> ## Documentation Index > Fetch the complete documentation index at: https://docs.nerdit.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > Deploy, inspect and operate an Engine from the terminal. Run `nerdit --help` or `nerdit COMMAND --help` for the help shipped with your installed version. This reference describes the 0.6.0 source interface; compare `nerdit --version` before using a command added after your installed release. ## Global options | Option | Purpose | | ---------------------- | ------------------------------------------------------- | | `--help` | Show top-level help. Also available on each command. | | `--version`, `-v` | Print the installed Nerdit version. | | `--show-completion` | Print shell completion for inspection or customization. | | `--install-completion` | Install completion for the current shell. | ## Choose the Engine The CLI reads `~/.nerdit/config.toml`. Its local destination is loopback on `[daemon].port`. A `[client].remote_host` selects the remote connection instead. `nerdit connect HOST --port PORT --token TOKEN` checks and saves a remote connection; it changes where subsequent CLI commands run. The CLI uses HTTP for this direct connection, so use a trusted network or a protected tunnel and avoid putting real tokens in shared shell history. There is no `NERDIT_CONFIG` environment variable or global `--config` selector in this version. The Engine configuration is separate from a project's `nerdit.toml`. ## Common workflows ```bash theme={null} nerdit doctor nerdit capabilities --json nerdit deploy ./my-app --dry-run nerdit deploy ./my-app --wait --timeout 300 nerdit services list nerdit logs my-app --follow nerdit diagnose my-app nerdit services restart my-app ``` Use explicit subcommands: `nerdit services list`, `nerdit models list` and `nerdit db list`. Their bare groups display help. For scripted waits, exit code `0` means convergence, `1` means failure or a superseding deploy, `2` is a usage error, and `3` is a wait timeout. A timeout does not cancel the deployment. Use the [HTTP API](/engine/http-api) for structured resource responses instead of parsing terminal tables. `services rm`, `gc`, `db restore`, `restore`, `unlink`, `uninstall` and credential changes can remove resources or access. Read the relevant [operations](/engine/operations), [recovery](/engine/backup-recovery) and [security](/engine/security) guide before using them. Plain `nerdit token` prints the selected credential: keep it out of recordings and logs. The commands below are generated from the registered CLI. They are an inventory of the available interface; optional cloud, GPU, model and database actions still require their respective prerequisites. ## Command reference Check system dependencies and optionally install missing ones. | Argument or option | Purpose | | ------------------ | ----------------------------------------------------------------------------------- | | `--install, -i` | Offer to install missing dependencies (with confirmation) Default: `False`. | | `--json` | Emit the check results as JSON (for scripting) instead of a table Default: `False`. | Initialize Nerdit: configuration, daemon, and GPU detection. | Argument or option | Purpose | | ------------------- | ---------------------------------------------------------------------------------------- | | `--project` | Generate a nerdit.toml in the current directory Default: `False`. | | `--auth-token-only` | Write only \[daemon].auth\_token if absent, then exit (installer use). Default: `False`. | Register a service from nerdit.toml \[deploy] + CLI flags, or serve a model. | Argument or option | Purpose | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `PATH` | App directory holding nerdit.toml (default: current directory), or a model reference like 'llama3.1:8b' to serve a local model | | `--image, -i` | Prebuilt image to run (required for an image service) | | `--name, -n` | Service name (DNS label) | | `--port, -p` | Container port to publish | | `--gpus, -g` | GPUs the service needs | | `--backend, -b` | Model serving backend: ollama (CPU/GPU) or vllm (GPU-only). Model serves only; default from the daemon config. | | `--max-model-len` | Model serves (vLLM) only: cap the context window (256-262144) | | `--gpu-memory-utilization` | Model serves (vLLM) only: VRAM fraction the engine may claim (0.1-0.95) | | `--restart-policy` | no \| on-failure \| always (default: always) | | `--command, -c` | Override the image CMD with a shell command | | `--script` | Run a script under the image's nerdit-runtime | | `--health` | HTTP path to probe for health (e.g. /healthz) | Deploy an app folder (zip + upload) or a Git URL, then build server-side. | Argument or option | Purpose | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PATH` | App directory to deploy (default: current directory) | | `--name, -n` | Service name (DNS label; default: \[deploy].name or folder) | | `--port, -p` | Container port the app listens on | | `--gpus, -g` | GPUs the app needs | | `--start` | Start command override | | `--health` | HTTP path to probe for health (e.g. /healthz) | | `--env, -e` | Environment variable KEY=VAL (repeatable) | | `--unset-env` | Environment variable KEY to delete on redeploy (repeatable) | | `--vendor` | Force a GPU vendor | | `--rollback` | Roll back to the previous deployed version (no build) Default: `False`. | | `--repo` | Deploy from a Git URL instead of a local folder | | `--ref` | Git branch or tag to clone (requires --repo) | | `--subdir` | Subdirectory within the repo to deploy (requires --repo) | | `--token-ref` | Secret reference for a private repo, e.g. ${secrets.shared.GITHUB_TOKEN}, or $\{github.installation} on a linked node with the Nerdit GitHub App (requires --repo) | | `--wait` | Block until the deploy converges (healthy) or fails. Exit codes: 0 converged, 1 failed or superseded, 3 timeout. Default: `False`. | | `--timeout` | Seconds to wait with --wait (server-clamped to \[1, 300]) Default: `60`. | | `--dry-run` | Validate + print the plan diff without deploying (no build, no write) Default: `False`. | Watch a folder and redeploy on every change (Ctrl-C to stop). | Argument or option | Purpose | | ------------------ | ------------------------------------------------------------------------------- | | `PATH` | App directory to watch (default: current directory) | | `--name, -n` | Service name (default: the nerdit.toml deploy name, else the folder name) | | `--timeout` | Seconds to wait for each redeploy (server-clamped to \[1, 300]) Default: `120`. | Display logs for a service (resolved by id or name). | Argument or option | Purpose | | ------------------ | ------------------------------------------------------------------------------ | | `TARGET` | Service id or name Required. | | `--follow, -f` | Follow logs continuously Default: `False`. | | `--grep, -g` | Keep only lines containing this text (a literal substring, not a regex) | | `--since` | Only lines at or after this ISO-8601 UTC timestamp (e.g. 2026-08-07T10:00:00Z) | Connect the CLI to a remote daemon. | Argument or option | Purpose | | ------------------ | --------------------------------------- | | `HOST` | Server IP address or hostname Required. | | `--port, -p` | Daemon port Default: `9321`. | | `--token, -t` | Authentication token Required. | Run the Nerdit MCP server over stdio (requires the `mcp` extra). Stop the nerditd daemon. | Argument or option | Purpose | | ------------------ | -------------------------------------------------------------- | | `--yes, -y` | Skip the confirmation prompt (for scripting) Default: `False`. | Fetch and install the daemon's internal CA root certificate. | Argument or option | Purpose | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | `--fingerprint` | Expected CA fingerprint (sha256:\, as logged by the daemon at startup). Skips the interactive confirmation; a mismatch aborts. | | `--output, -o` | Write the verified root certificate to PATH instead of installing it. | Remove a previously trusted internal CA from this machine's trust store. | Argument or option | Purpose | | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `--fingerprint` | Only untrust the CA with this fingerprint (sha256:\). Without it, every saved Nerdit CA under \~/.nerdit is offered. | | `--yes, -y` | Do not prompt before removing each CA from the trust store. Default: `False`. | Link this daemon (code, --device or --key-stdin), refresh metadata, or show status. | Argument or option | Purpose | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CODE` | Link code from the cloud console. Omit it while passing --api-url to be prompted instead (keeps the code out of shell history); omit everything to show link status. The literal 'refresh' re-reads the cloud's hosted domain instead of claiming. To link without a console code, use --device (approve in a browser) or --key-stdin (a pre-auth key on stdin) — neither takes a positional code. | | `--api-url` | Cloud API origin to claim against. Defaults to [https://app.nerdit.ai](https://app.nerdit.ai). Used for this claim only — never stored. | | `--relay-url` | Relay endpoint to persist as \[link].relay\_url. Omit to keep the one already configured; on a node with none, defaults to wss\://relay.nerdit.ai/v1/connect. | | `--enable, --no-enable` | Also set \[link].enabled = true in the same write. Default: `True`. | | `--device` | Link by approving this node in a browser — no code to copy. Prints a one-click URL and waits for the approval. Default: `False`. | | `--key-stdin` | Link with a pre-auth key read from stdin (never an option value, so it stays off argv). Falls back to a hidden prompt on a terminal. Default: `False`. | | `--timeout` | Seconds to wait for a --device approval before giving up (exit 3). Default: `600`. | Revoke this daemon's cloud link: drop the tunnel and wipe its identity. | Argument or option | Purpose | | ------------------ | ------------------------------------------------- | | `--yes, -y` | Do not prompt for confirmation. Default: `False`. | Share a deployed app at a hosted URL through this node's cloud link. | Argument or option | Purpose | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NAME` | Name of the deployed app to share. Required. | | `--public` | Make the URL world-reachable instead of owner-only. Needs an entitled account AND either --consent or a \[deploy].edge\_auth block on the app. Default: `False`. | | `--consent` | Acknowledge that --public means anyone with the link can open the app. Default: `False`. | | `--show` | Print the current share instead of changing it. Default: `False`. | Remove an app's hosted share; the URL stops answering on the next request. | Argument or option | Purpose | | ------------------ | ------------------------------------------ | | `NAME` | Name of the app to stop sharing. Required. | Remove this installation, its containers, images, data and credentials. | Argument or option | Purpose | | ------------------ | --------------------------------------------------------------------------------------------- | | `--yes, -y` | Skip the typed confirmation prompt. Default: `False`. | | `--dry-run` | Show what would be removed and exit without touching anything. Default: `False`. | | `--purge-images` | Also remove the base images (Ollama/vLLM/Postgres/Redis/runtime). Default: `False`. | | `--keep-data` | Preserve the data dir and secrets key; still remove containers/images/logs. Default: `False`. | Update (or downgrade) an installed nerdit to the latest or a pinned release. | Argument or option | Purpose | | ------------------ | ------------------------------------------------------------------------------ | | `--version` | Install this exact release (e.g. 0.5.0) instead of the latest. Downgrades too. | | `--yes, -y` | Do not prompt for confirmation. Default: `False`. | Explain why a service failed and what to do about it (one bounded call). | Argument or option | Purpose | | ------------------ | ------------------------------------------------------------------- | | `NAME` | Service name or id to diagnose Required. | | `--log-tail` | Log lines to show (clamped server-side to \[1, 200]) Default: `50`. | Diagnose the daemon: run its structured health checks and print them. Show what this daemon can do, and what the current token may do. | Argument or option | Purpose | | ------------------ | ------------------------------------------ | | `--json` | Print the raw JSON body. Default: `False`. | List every registered route (models included, shown as unrouted). | Argument or option | Purpose | | ------------------ | ----------------------------------- | | `--limit` | Max rows per page. Default: `50`. | | `--cursor` | Opaque cursor from a previous page. | Show what the daemon did on its own: deploys, health flaps, restarts, failures. | Argument or option | Purpose | | ------------------ | -------------------------------------------------------------------------------------------------------------------- | | `--follow, -f` | Stream new events as they happen. Default: `False`. | | `--since` | Replay forwards from this event id (id ASC, oldest first) — the resume mode. Without it the feed reads newest-first. | | `--type` | Only this event type (repeatable, at most 10 honoured). | | `--service` | Only this service name. | | `--limit` | Max rows (clamped server-side to 200). Default: `50`. | Show disk usage: docker totals + named-volume/model/archive/backup trees. Garbage-collect orphan app images (and, opt-in, orphan data dirs). | Argument or option | Purpose | | ----------------------- | -------------------------------------------------------------------------------- | | `--dry-run` | Only show what would be reclaimed. Default: `False`. | | `--yes, -y` | Skip the confirmation prompt. Default: `False`. | | `--include-orphan-data` | Also delete service data dirs with no live row (IRREVERSIBLE). Default: `False`. | Stage a backup tar. | Argument or option | Purpose | | ------------------ | ------------------------------------------------------------------------------- | | `--volume` | Capture a managed database's data volumes (backup v2) instead of control-plane. | | `--yes, -y` | Skip the custody confirmation. Default: `False`. | Restore state from a backup tar — **daemon must be stopped**. | Argument or option | Purpose | | ------------------ | ------------------------------------------------------------------------------------------------------- | | `TAR_PATH` | Path to a nerdit-\*.tar.gz archive. Required. | | `--volume` | Restore a per-database volume tar (nerdit-volumes-\*) instead of control-plane state. Default: `False`. | | `--yes, -y` | Skip the overwrite confirmation. Default: `False`. | Create a scoped API token (admin token required). | Argument or option | Purpose | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `NAME` | Human-readable label for the token. Required. | | `--role` | admin \| submitter \| readonly. Default: `submitter`. | | `--max-gpus` | Cumulative GPU cap across active jobs. | | `--max-concurrent-jobs` | Concurrent active-job cap. | | `--expires-in` | Lifetime: seconds (3600) or a suffixed duration (24h, 30d). Omitted uses the daemon's \[security].token\_default\_ttl\_s. | | `--scope` | Restrict this token to a service (repeatable). Admin tokens cannot be scoped. | List API tokens (admin token required). Hashes/plaintext are never shown. | Argument or option | Purpose | | ------------------- | ------------------------------------------- | | `--include-revoked` | Also show revoked tokens. Default: `False`. | Show the token this CLI is authenticating with (any role). Rotate this token's secret in place; the new value is shown once. | Argument or option | Purpose | | ------------------ | --------------------------------------------------------------------------------- | | `--extend` | Also push the expiry forward (rotation never extends silently). Default: `False`. | | `--expires-in` | New lifetime: seconds (3600) or a suffixed duration (24h, 30d). Implies --extend. | Revoke an API token (admin token required). | Argument or option | Purpose | | ------------------ | ----------------------------- | | `TOKEN_ID` | Token id to revoke. Required. | Show daemon configuration (secrets redacted). | Argument or option | Purpose | | ------------------ | ------------------------------------- | | `SECTION` | Section name (omit for all sections). | Update daemon configuration keys (admin token required). | Argument or option | Purpose | | ------------------ | ------------------------------------------------ | | `SECTION` | Section name (e.g. services). Required. | | `PAIRS` | One or more key=value assignments. Required. | | `--dry-run` | Show the diff without writing. Default: `False`. | Declaratively apply a multi-section daemon config document. | Argument or option | Purpose | | ------------------ | ------------------------------------------------ | | `PATH` | TOML file to apply, or '-' for stdin. Required. | | `--dry-run` | Show the diff without writing. Default: `False`. | Show a deployed app's config (deploy fields, ai bindings, source/revision). | Argument or option | Purpose | | ------------------ | ---------------------------- | | `NAME` | Deployed app name. Required. | Update a deployed app's config section (admin/owner token required). | Argument or option | Purpose | | ------------------ | --------------------------------------------------------- | | `NAME` | Deployed app name. Required. | | `SECTION` | Section name (deploy or ai). Required. | | `PAIRS` | One or more key=value assignments. Required. | | `--dry-run` | Show the diff without writing. Default: `False`. | | `--restart` | Restart the service after a real write. Default: `False`. | List services (bounded, newest first). | Argument or option | Purpose | | ------------------ | ---------------------- | | `--status` | Filter by exact status | Stop a service (desired\_state → stopped). | Argument or option | Purpose | | ------------------ | ---------------------------- | | `NAME` | Service id or name Required. | Restart a service (desired\_state → running, backoff cleared). | Argument or option | Purpose | | ------------------ | ---------------------------- | | `NAME` | Service id or name Required. | Rebuild a service from its recorded Git repository and ref. | Argument or option | Purpose | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `NAME` | Service name Required. | | `--wait` | Block until the redeploy converges (healthy) or fails. Exit codes: 0 converged, 1 failed or superseded, 3 timeout. Default: `False`. | | `--timeout` | Seconds to wait with --wait (server-clamped to \[1, 300]) Default: `60`. | | `--dry-run` | Validate + print the plan diff without deploying (no write) Default: `False`. | Remove a service (tear down the container + delete the row). | Argument or option | Purpose | | ------------------ | -------------------------------------------------------------------------------------- | | `NAME` | Service id or name Required. | | `--purge` | CSV of purge targets: secrets,data,images Default: `secrets`. | | `--force` | Bypass the model-reference and active-run guards (may require admin) Default: `False`. | | `--yes, -y` | Skip the data-purge confirmation Default: `False`. | Wait for a service's deploy outcome. | Argument or option | Purpose | | ------------------ | -------------------------------------------------------------- | | `NAME` | Service id or name Required. | | `--timeout` | Seconds to block (server-clamped to \[1, 300]) Default: `60`. | | `--version` | Deploy generation to wait on; a newer one reports 'superseded' | Show live CPU, memory and network usage, cached for two seconds. | Argument or option | Purpose | | ------------------ | ---------------------------- | | `NAME` | Service id or name Required. | Run a bounded command in the service's image without changing the service. | Argument or option | Purpose | | ------------------ | ----------------------------------------------------------------------------------- | | `NAME` | Service id or name Required. | | `COMMAND` | Command to execute, after a `--` separator (e.g. -- alembic upgrade head) Required. | | `--timeout-s` | Seconds the command may run before it is killed Default: `300`. | | `--env, -e` | Environment override KEY=VAL for this run only (repeatable) | | `--tail` | Log lines to print (server-bounded: must be within \[1, 200]) Default: `200`. | Set/merge secrets for a service (values are write-only). | Argument or option | Purpose | | ------------------ | ---------------------------------------------------------------------- | | `SERVICE` | Service name | | `PAIRS` | Secret KEY=VAL pairs | | `--shared` | Target the global shared scope instead of a service. Default: `False`. | List a service's secret key names (values are never shown). | Argument or option | Purpose | | ------------------ | ---------------------------------------------------------------------- | | `SERVICE` | Service name | | `--shared` | Target the global shared scope instead of a service. Default: `False`. | Delete one secret key, or all of a service's secrets. | Argument or option | Purpose | | ------------------ | ---------------------------------------------------------------------- | | `SERVICE` | Service name | | `--key, -k` | Delete a single key (default: all secrets) | | `--shared` | Target the global shared scope instead of a service. Default: `False`. | Rotate the secrets-at-rest encryption key (admin-only). List served models (bounded, newest first). Provision a managed database (kind=database desired-state workload). | Argument or option | Purpose | | ------------------ | --------------------------------------------------------------------- | | `BACKEND` | Data backend to provision: postgres \| redis (default: daemon config) | | `--name, -n` | Database name (DNS label; default: the backend's prefix) | | `--wait, -w` | Block until the database is ready Default: `False`. | | `--timeout, -t` | --wait timeout in seconds Default: `120`. | List managed databases (bounded, newest first). Capture a logical, application-consistent dump of a managed database. | Argument or option | Purpose | | ------------------ | ----------------------------------------------------------------- | | `NAME` | Managed database name (as shown by `nerdit db list`) Required. | | `--timeout-s` | Seconds the dump tool may run before it is killed Default: `900`. | | `--yes, -y` | Skip the custody confirmation. Default: `False`. | List the dump archives this daemon holds for one database (newest first). | Argument or option | Purpose | | ------------------ | ------------------------------- | | `NAME` | Managed database name Required. | Restore a dump into a managed database — **destructive**. | Argument or option | Purpose | | ------------------ | --------------------------------------------------------------------------------- | | `NAME` | Managed database to restore INTO Required. | | `DUMP` | Dump basename as listed by `nerdit db dumps` (a basename, never a path) Required. | | `--force` | Restore even while running apps are bound to this database. Default: `False`. | | `--timeout-s` | Seconds the restore may run before it is killed Default: `600`. | | `--yes, -y` | Skip the typed confirmation. Default: `False`. | List the app template catalog. Show one template's coordinates, defaults and env schema. | Argument or option | Purpose | | ------------------ | --------------------- | | `TEMPLATE_ID` | Template id Required. | Deploy an app template: clone the catalog repo server-side, build, run. | Argument or option | Purpose | | ------------------ | ---------------------------------------------- | | `TEMPLATE_ID` | Template id Required. | | `--name, -n` | Service name (DNS label) Required. | | `--env, -e` | Environment variable KEY=VAL (repeatable) | | `--secret, -s` | Secret KEY=VAL written write-only (repeatable) | | `--port, -p` | Container port override | | `--gpus, -g` | GPUs the app needs | | `--start` | Start command override | | `--health` | HTTP health path override | | `--vendor` | Force a GPU vendor | Show the embedded proxy's state, TLS, apex, respawn and route counts. Restart the daemon to apply restart-required config (admin-only, audited). | Argument or option | Purpose | | ------------------- | ------------------------------------------------------------------------------------- | | `--drain-timeout-s` | Seconds to drain in-flight builds and runs (server-clamped \[0, 300]). Default: `60`. | | `--yes, -y` | Skip the confirmation prompt. Default: `False`. | | `--wait` | Block until the daemon answers again. Default: `False`. | | `--wait-timeout` | Seconds to wait for the daemon to come back (with --wait). Default: `60`. | List an app's direct domains. | Argument or option | Purpose | | ------------------ | ----------------------------------- | | `APP` | Name of the deployed app. Required. | Add a direct domain to a deployed app. | Argument or option | Purpose | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `APP` | Name of the deployed app. Required. | | `DOMAIN` | Bare DNS name you control, e.g. app.example.com. Required. | | `--acme, --no-acme` | Request a public certificate via ACME HTTP-01. Needs an admin token and \[proxy.acme].enabled on the daemon (409 domain.acme\_disabled / 403 domain.acme\_forbidden otherwise). --no-acme serves the name with this node's internal CA; neither flag keeps an existing domain's current setting. | Remove a direct domain; the route disappears on the next reconcile tick. | Argument or option | Purpose | | ------------------ | -------------------------------------- | | `APP` | Name of the deployed app. Required. | | `DOMAIN` | The direct domain to remove. Required. | Install a signed license file on the daemon (admin). | Argument or option | Purpose | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | `FILE` | Path to the license file, or '-' to read it from stdin. Omit it to read piped stdin. The blob itself is never accepted as an argument. | Show the persisted license path and what the running daemon verified. Delete the installed license from the daemon (admin). | Argument or option | Purpose | | ------------------ | ------------------------------------------------- | | `--yes, -y` | Do not prompt for confirmation. Default: `False`. |