CLI reference

numes is one executable. It runs the terminal UI, guided setup, the serving daemon and the commands below, and it starts coding agents on Numes models with numes run, which needs no provider setup. Run any command with --help for its usage and units. Install and update covers installing it.

numes COMMAND [SUBCOMMAND] [OPTIONS]            # sign-in, accounts, coding agents and the installationnumes provider COMMAND [SUBCOMMAND] [OPTIONS]   # everything about serving inference

With no command, numes prints help; numes provider prints the provider commands.

General options

Commands that talk to the platform use your saved sign-in. If none is saved and the command is interactive, it signs you in first. Non-interactive commands, and --json commands without an explicit --login-method, fail instead of prompting.

Files and environment variables

Secrets are never arguments

Options whose names suggest a secret, such as tokens, credentials, private keys or secrets, are rejected. Two options take a typed reference instead of a value: --api-key-secret and --resource-configuration-secret accept env://NAME or local://NAME. --api-key-env NAME is shorthand for --api-key-secret env://NAME. Keys you type at a prompt go to the profile's owner-only secret store. See Profiles and configuration.

Exit codes

Errors go to standard error as numes: MESSAGE and never include secrets. numes run exits with the agent's exit code.

Commands

numes help and numes provider help print general and provider help.

run

numes runnumes run [OPTIONS] opencode|pi|omp [AGENT ARGUMENTS...]

Without an agent, lists the supported agents, whether each is installed and the version Numes tests with. With one, refreshes the agent's model list from the models your inference key can use, writes its configuration and starts it in this terminal. Options for numes run come before the agent's name; everything after it goes to the agent unchanged. The first launch asks you to paste a key or sign in and create one. See Coding agents.

bridge

numes bridge

Starts an OpenAI-compatible API on this machine's loopback address for end-to-end encrypted (:e2ee) models, using your saved inference key. Set NUMES_E2EE_BRIDGE_KEY to a private 32–256 character key first; clients use that key with the printed base URL. Ctrl+C stops it. See Encrypted inference.

auth

numes auth login [--login-method auto|loopback|device]numes auth statusnumes auth logout [--login-method loopback|device]

login always starts a new sign-in. auto uses a device code over SSH, on Linux without a graphical display, or when the terminal isn't interactive, and a browser on this machine otherwise. status reads local state only. logout revokes and removes the saved sign-in; with a method, only that method's.

auth key

numes auth key set [--paste | --create] [create options]numes auth key statusnumes auth key remove [--revoke | --keep-previous]

Manages the inference key numes run uses, separately from your sign-in. set replaces it and takes the same options as numes run. status shows the key's name, currency, limit and state, never the key, and notes when NUMES_API_KEY overrides it. remove forgets the key on this machine. When a key that numes created is replaced or removed, numes offers to revoke it; revoke a pasted key in Keys.

account

numes account list

Lists the personal and organization accounts you can act for, with the IDs setup --account takes.

version

numes versionnumes --version

Prints the release version followed by the exact build, for example 0.1.0 (source-0123…).

update

numes update [--check | --retry]

Installs a newer release from the release feed, restarts each background service on it, and restores the previous release if a service doesn't reconnect. A profile started without a background service keeps running the earlier release until you restart it; update lists each one it finds. --check only reports whether a newer release exists. A release that was rolled back on this machine isn't installed again automatically; --retry tries it once more. Works only for installations made by the installer or the desktop app. See Install and update.

uninstall

numes uninstallnumes uninstall --purge --confirm

Removes every profile's background service, the updater, the command link and every installed release. Profiles, your sign-in, the saved inference key and agent sessions stay unless you add --purge --confirm. Nothing on the platform is deleted.

install

numes install [--manifest FILE]

Installs the running executable into ~/.local/share/numes and links the command. With --manifest, it first checks that the release manifest names this executable's exact digest, size and, where required, signature. The installer runs this for you.

tui

numes provider tui [--profile NAME]

Opens the terminal UI, optionally with an endpoint selected. It needs an interactive terminal.

setup

numes provider setup SOURCE [OPTIONS]numes provider setup --resume PROFILE [--plan | --start [--wait-ready]] [--skip-failing-models] [--include-kept-models]numes provider setup --list-draftsnumes provider setup --resume PROFILE --discard

Setup signs you in if needed, selects the account and provider, connects the source, discovers and selects models, prices them, creates or reuses the provider and endpoint, publishes the models and optionally starts the daemon. Interactive setup prompts for anything missing and asks for one confirmation before publishing. Without --provider, --provider-name or --reuse-provider-from, it lists the account's self-hosted providers, such as one you created in the dashboard, then Create a new provider. With --non-interactive, or when input isn't a terminal, every required value must be a flag. Every change is saved to a resumable draft.

SOURCE is a source kind, such as ollama, vllm, llama-cpp, openai-compatible, openrouter, openai, anthropic, google-gemini, kimi-code, opencode-zen, ppq, deepinfra, novita, venice or tinfoil. numes provider source kinds lists them; Inference sources describes each.

Setup modes

When a model fails its checks

Before anything is created on the platform, setup checks every selected model against the source: chat, tools, reasoning and the other capabilities it declares. Every model is checked, even after one fails, so one run reports them all.

By default a failed model stops the publication and nothing is submitted. Setup prints each model's outcome (state capability_validation_failed, with the failed check and verdict per model) and exits with status 1. Fix the source or the model's settings, then run setup --resume PROFILE again.

To publish the models that passed, resume with --skip-failing-models. The failed models stay in the draft, kept for later with their terms; the result lists them under kept_for_later with each one's failed check. Once they pass, run setup --resume PROFILE --include-kept-models to check and publish them as the endpoint's next revision. Only the kept models are published: models you already published keep their current terms, including any changes you made to the endpoint since setup.

Models and source options

Price options

A price flag is needed only when the model reports usage for that meter. --free and --share-with-organization can't be combined with reference prices, markup or non-zero prices. See Pricing your models.

Provider and endpoint options

Capacity and data policy options

Data declarations are binding commitments under the provider terms. Inaccurate declarations lead to suspension and withholding of earnings.

Examples:

# Ollama, published and started in one commandnumes provider setup ollama --profile ollama-local \  --provider-name "Example Labs" --model llama3.2:3b \  --canonical-model llama3.2:3b=meta-llama/llama-3.2-3b-instruct \  --currency USD --prompt-price 0.10 --completion-price 0.40 \  --non-interactive --start --wait-ready​# OpenRouter, reference prices plus 15%, planned firstnumes provider setup openrouter --profile cloud \  --api-key-env OPENROUTER_API_KEY --model example-author/example-model \  --provider-name "Example Labs" --currency USD --markup-percent 15 \  --plan --non-interactive

status

numes provider status --profile NAME [--local]

Reports one combined readiness state, the next action, source health, platform connection, configured and accepted terms, and the provider, endpoint and model statuses. --local skips sign-in and the platform lookup. See Readiness states.

profile

numes provider profile listnumes provider profile start --profile NAME | --allnumes provider profile stop|status|doctor|validate|edit|logs --profile NAMEnumes provider profile remove --profile NAME --confirm [--keep-endpoint]

Aliases: numes provider doctor, logs and stop run the matching profile subcommand.

service

numes provider service install --profile NAME [--manual-start]numes provider service status --profile NAMEnumes provider service remove --profile NAME

Runs a profile as a per-user background service (a systemd user service on Linux, a LaunchAgent on macOS) that restarts after a failure and starts after a reboot.

The service always runs the installed release. The command never overwrites a service it didn't create, and refuses when the profile reads a secret from an environment variable the service wouldn't have. On Linux without lingering, user services stop at logout; the command enables lingering when it can and otherwise prints sudo loginctl enable-linger <user> for an administrator. See Keep it running.

config

numes provider config path|show|validate|edit --profile NAMEnumes provider config show --profile NAME --effective

path prints the location of profile.toml. show redacts secrets and private connection details; --effective also lists which PROVIDER_* override names are set and whether they apply, never their values. See Profiles and configuration.

source

numes provider source kindsnumes provider source probe|version --profile NAMEnumes provider source configure --profile NAME --kind KIND [OPTIONS]numes provider source auth login|status|logout --profile NAME

models

numes provider models discover|list --profile NAMEnumes provider models inspect --profile NAME --model IDnumes provider models select|unselect --profile NAME --model ID [--model ID ...]numes provider models refresh --profile NAME [--accept-reference-prices]  [--markup-percent DECIMAL] [--market-adjustment DECIMAL]numes provider models identity --profile NAME --model ID  [--action resolve|accept-change|retry-completion]  [--canonical-id publisher/model] [--origin CHAIN] [--enrich-origins]

discover lists what the source offers now, on any profile. list and inspect show the draft before the first publication and the published models after it, read from the platform with your sign-in. If this version can't show the published terms exactly, they refuse; manifest preview then prints the published manifest, unless a number in it can't be shown exactly either. select, unselect and refresh edit the draft before the first publication; after that, change models in the terminal UI or desktop app. refresh keeps your prices unless --accept-reference-prices replaces them with current references.

identity also works on published profiles:

An approved name never replaces verification.

prices

numes provider prices show --profile NAMEnumes provider prices set --profile NAME --model ID --meter TYPE \  --currency USD|BTC --cost DECIMAL --unit UNIT \  [--pricing-basis fixed|usd_indexed] [--sku ID]numes provider prices unset --profile NAME --model ID --meter TYPE \  --currency USD|BTC [--sku ID]

TYPE is prompt, cached_prompt, cache_write, completion, internal_reasoning, request or sku. UNIT is call, character, image, megabyte, page, request, search, second or token, as the model's usage allows. Token costs are per 1M tokens; other costs are per unit. usd_indexed needs --currency BTC and a USD cost. show works on any profile: before the first publication it shows the draft, after it the published prices. Like models list, it refuses when it can't show the published terms exactly. set and unset work only before the first publication.

manifest

numes provider manifest preview|diff --profile NAMEnumes provider manifest publish --profile NAME [--plan]numes provider publish --profile NAME [--plan]numes provider manifest sync --profile NAMEnumes provider manifest recover --profile NAME [--choose FIELD=local|server ...] [--confirm]

publish (or the publish shorthand) works on an unpublished draft. publish reloads a running profile; a stopped one uses the new terms on its next start. --plan shows the revision, models and price count without publishing. preview and diff work on any profile: after the first publication, preview prints the published manifest (or refuses if a number in it can't be shown exactly) and diff shows there are no local changes, because published terms are edited in the terminal UI or desktop app. sync adopts the terms the platform last accepted for a published endpoint, without changing local credentials or source settings. When sync preserves conflicting local edits, recover lists the conflicts; choose local or server for each and add --confirm to apply them. Edit and publish the terms of an existing endpoint in the terminal UI or desktop app.

capacity

numes provider capacity edit --profile NAME --maximum-concurrent INTEGER

On a published profile, --maximum-concurrent changes only the local ceiling and applies it to the running daemon at once; it can't raise the published capacity. To change published capacity, edit it in the terminal UI or desktop app and publish.

verification

numes provider verification retry --profile NAME [--model ID]

Runs the profile doctor first and refuses unless the source, selected models, secrets, endpoint identity, credential and platform connection are ready. Then it retries a targeted recovery check for each model whose platform status allows it, or only --model. A failed initial full check uses bounded automatic retries; further full checks require our team. It never publishes. See Verification.

autopilot

numes provider autopilot status|refresh --profile NAMEnumes provider autopilot preview|enable|set --profile NAME [--markup-percent N]  [--models selected|all] [--add-new-models|--no-add-new-models]  [--exclude ID,ID] [--currency USD|BTC|both] [--cost-guard on|off] [--yes]numes provider autopilot disable --profile NAME

Autopilot settings are stored on the platform for the profile's endpoint, and the running agent applies them. preview shows the model list autopilot would publish; enable, and set while autopilot is on, publish it only with --yes. Options you leave out keep their values. If the settings changed after the command read them, nothing changes. refresh asks the agent to check again and needs autopilot to be on. Models put on autopilot one by one in the dashboard show as listed; --models replaces that choice. See Autopilot.

review

numes provider review save-provider --profile NAME --name DISPLAY_NAMEnumes provider review submit-provider --profile NAMEnumes provider review endpoint --profile NAMEnumes provider review save-endpoint|submit-endpoint --profile NAME [OPTIONS]

save-endpoint and submit-endpoint take --name, --collects-data true|false, --retention none|limited|indefinite|unknown, --retention-days N, --countries CODES and --regions REGIONS, with comma-separated lists. See Review and lifecycle.

Platform views

numes provider remote status|operations|earnings|withdrawals --profile NAME

Read-only views of the platform's records for the profile's provider:

daemon

numes provider daemon --profile NAME

Runs the profile's daemon in the foreground until it receives a termination signal, then finishes accepted requests and exits. Use it under a service manager or container supervisor you manage; service install sets up a per-user service for you.

Next steps