CLI reference

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

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 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, recovery and 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

nerdit check-deps

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`.

nerdit init

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`.

nerdit serve

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)

nerdit deploy

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`.

nerdit dev

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`.

nerdit logs

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)

nerdit connect

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.

nerdit mcp

Run the Nerdit MCP server over stdio (requires the mcp extra).

nerdit exit

Stop the nerditd daemon.

Argument or option	Purpose
`--yes, -y`	Skip the confirmation prompt (for scripting) Default: `False`.

nerdit trust

Fetch and install the daemon’s internal CA root certificate.

Argument or option	Purpose
`--fingerprint`	Expected CA fingerprint (sha256:<hex>, 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.

nerdit untrust

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:<hex>). 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`.

nerdit link

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. 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`.

nerdit unlink

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`.

nerdit unshare

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.

nerdit uninstall

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`.

nerdit update

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`.

nerdit diagnose

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`.

nerdit doctor

Diagnose the daemon: run its structured health checks and print them.

nerdit capabilities

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`.

nerdit routes

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.

nerdit events

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`.

nerdit disk

Show disk usage: docker totals + named-volume/model/archive/backup trees.

nerdit gc

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`.

nerdit backup

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`.

nerdit restore

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`.

nerdit token create

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.

nerdit token list

List API tokens (admin token required). Hashes/plaintext are never shown.

Argument or option	Purpose
`--include-revoked`	Also show revoked tokens. Default: `False`.

nerdit token whoami

Show the token this CLI is authenticating with (any role).

nerdit token rotate

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.

nerdit token revoke

Revoke an API token (admin token required).

Argument or option	Purpose
`TOKEN_ID`	Token id to revoke. Required.

nerdit config get

Show daemon configuration (secrets redacted).

Argument or option	Purpose
`SECTION`	Section name (omit for all sections).

nerdit config set

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`.

nerdit config apply

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`.

nerdit config app get

Show a deployed app’s config (deploy fields, ai bindings, source/revision).

Argument or option	Purpose
`NAME`	Deployed app name. Required.

nerdit config app set

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`.

nerdit services list

List services (bounded, newest first).

Argument or option	Purpose
`--status`	Filter by exact status

nerdit services stop

Stop a service (desired_state → stopped).

Argument or option	Purpose
`NAME`	Service id or name Required.

nerdit services restart

Restart a service (desired_state → running, backoff cleared).

Argument or option	Purpose
`NAME`	Service id or name Required.

nerdit services redeploy

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`.

nerdit services rm

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`.

nerdit services wait

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’

nerdit services stats

Show live CPU, memory and network usage, cached for two seconds.

Argument or option	Purpose
`NAME`	Service id or name Required.

nerdit services run

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`.

nerdit secrets set

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`.

nerdit secrets list

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`.

nerdit secrets rm

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`.

nerdit secrets rotate-key

Rotate the secrets-at-rest encryption key (admin-only).

nerdit models list

List served models (bounded, newest first).

nerdit db create

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`.

nerdit db list

List managed databases (bounded, newest first).

nerdit db dump

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`.

nerdit db dumps

List the dump archives this daemon holds for one database (newest first).

Argument or option	Purpose
`NAME`	Managed database name Required.

nerdit db restore

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`.

nerdit store list

List the app template catalog.

nerdit store show

Show one template’s coordinates, defaults and env schema.

Argument or option	Purpose
`TEMPLATE_ID`	Template id Required.

nerdit store deploy

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

nerdit proxy status

Show the embedded proxy’s state, TLS, apex, respawn and route counts.

nerdit daemon restart

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`.

nerdit domains list

List an app’s direct domains.

Argument or option	Purpose
`APP`	Name of the deployed app. Required.

nerdit domains add

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.

nerdit domains remove

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.

nerdit license install

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.

nerdit license status

Show the persisted license path and what the running daemon verified.

nerdit license remove

Delete the installed license from the daemon (admin).

Argument or option	Purpose
`--yes, -y`	Do not prompt for confirmation. Default: `False`.

Start here

Build and operate

Access and interfaces

HTTP endpoints

Get help

Global options

Choose the Engine

Common workflows

Command reference

​Global options

​Choose the Engine

​Common workflows

​Command reference

Global options

Choose the Engine

Common workflows

Command reference