CLI Reference¶
All commands are under basemode. Running basemode with no explicit subcommand defaults to run.
Generation¶
run¶
Generate continuation text (single stream or parallel branches).
| Option | Default | Description |
|---|---|---|
-m, --model |
stored default or gpt-4o-mini |
Model to use |
-n, --branches |
1 |
Number of parallel continuations |
-M, --max-tokens |
200 |
Max output tokens |
-t, --temperature |
0.9 |
Sampling temperature (when model allows) |
-s, --strategy |
auto | Force strategy selection |
--rewind |
false |
Hold back the last short token so word joins are exact (may reissue the request) |
--strict-max-tokens |
false |
Enforce the visible output limit client-side |
--show-strategy |
false |
Print selected strategy |
--show-usage |
false |
Print token estimate after generation |
--show-cost |
false |
Print estimated cost after generation |
-v, --verbose |
false |
Show content-free operation, attempt, outcome, and ledger events on stderr |
PREFIX can come from stdin when omitted.
ask¶
Ask a question and stream a normal chat answer. No continuation coercion: the
model answers as an assistant, through the same model normalization, keys and
provider quirks as run.
| Option | Default | Description |
|---|---|---|
-m, --model |
stored default or gpt-4o-mini |
Model to use |
-s, --system |
none | System prompt |
-M, --max-tokens |
4096 |
Max output tokens |
-t, --temperature |
0.7 |
Sampling temperature (when model allows) |
--transcript / --no-transcript |
auto | Force or skip the User:/Assistant: transcript used for base models |
--show-usage |
false |
Print token usage after the answer (stderr) |
--show-cost |
false |
Print estimated cost after the answer (stderr) |
-v, --verbose |
false |
Show content-free operation, attempt, outcome, and ledger events on stderr |
Piped or redirected stdin is prepended to PROMPT, separated by a blank line.
The answer is written verbatim to stdout and usage tables go to stderr, so
basemode ask ... > answer.md stays clean. A provider error prints one
error: line on stderr and exits 1.
Models litellm lists as completion-only (davinci-002,
gpt-3.5-turbo-instruct) have no chat endpoint. They are answered by extending
a User:/Assistant: transcript, cut off where the model starts the next user
turn. --transcript does the same for a base model served without a chat
template. Calls are recorded in health with strategy chat (or
chat_transcript).
Discovery¶
models¶
List known model endpoints. The list combines basemode's verified data, cached live provider catalogs, and LiteLLM's bundled catalog; fresh provider evidence takes precedence over stale bundled entries.
--availablelimits to providers with configured keys.--verifiedlimits to models tracked in the verified-models registry.--fullretains dated snapshots that are collapsed in the default view.--all-modesincludes image, audio, embedding, and other non-text models.--since 6mlimits results by release age; ISO dates are also accepted.--livequeries a provider's current catalog and requires--provider.--jsonemits structured picker metadata (provider, availability, reliability, pricing fields when known).--wire-idsshows exact provider IDs instead of canonical names.
Model listings and command summaries use lowercase canonical
provider/creator/model names. JSON listings expose this name as model, with
the exact provider spelling in wire_id. Canonical names can be copied into
model arguments for generation, inspection, rating, benchmarking and verification.
The Rating column shows your own thumbs (see rate); rated models sort to
the top or the bottom of the list.
rate¶
Rate a model up or down. Ratings are personal, stored in
~/.config/basemode/auth.json, and reorder every list built from the model
picker — basemode models, and any frontend on top of it.
basemode rate claude-opus-5 up
basemode rate gpt-4o down
basemode rate gpt-4o clear
basemode rate # list every rated model
health¶
Show what models actually did on this machine: attempts, failures, failure rate, and the categories they failed with. Recorded automatically by every continuation; see Keys and Defaults.
--verification shows durable verification-probe health instead of local
generation history.
providers¶
List all known providers.
strategies¶
List supported continuation strategies, followed by any per-model strategy pins stored on this machine.
info¶
Show normalized model ID, selected strategy and where that choice came from
(verified models registry, model-name heuristic, or a local pin), quirks,
token limits, pricing metadata, your rating, and observed health.
Tuning¶
verify¶
Run durable quick, thorough, or transient-failure verification. This makes real provider requests and stores each attempt in the unified observation ledger. See Verification for suite selection, planning, limits, recovery, and status effects.
basemode verify [MODEL...] [--suite quick|thorough|transient-recheck] [--attempts N] [--max-tokens N]
[--provider NAME] [--status STATUS] [--available] [--from-catalog] [--priced | --unpriced]
[--released-since YYYY-MM-DD | --max-release-age-days N]
[--stale-after-days N] [--dry-run] [-v | --quiet] [--json]
Sweeps run with bounded global and per-provider concurrency (--concurrency and
--per-provider-concurrency). Bound work with --max-probes, --max-requests,
--max-elapsed (seconds), and --max-cost-usd. Every underlying self-healing
request is retained and counts toward the request limit. A bounded run finishes
with status limited; continue it with basemode verify --resume RUN_ID.
Models are required for quick and thorough suites. With no models, the transient-recheck suite selects endpoints whose latest operational failure is suspected to be temporary and whose stored backoff timestamp is due. Explicit model arguments override queue selection for a deliberate manual recheck.
Selectors can plan deterministic catalog sweeps by provider, release date, and
current status (never-tested, reachable, broken, transient, verified,
stale, account-limited, or retired). Repeat provider and status options to
form unions. account-limited and retired endpoints are skipped unless named
or asked for by status. --dry-run
makes no provider requests and reports the ordered stages, provider counts,
logical probes, maximum self-healing requests, and a best-effort price ceiling.
--available supplies text-model candidates from every provider with a key on
this machine; combine it with --status never-tested for a useful first sweep.
Add -v to a live run to see each content-free probe, attempt, retry, outcome,
and ledger write as it happens. Logs go to stderr so generated text and JSON on
stdout remain usable.
Verification is verbose by default; use --quiet to suppress these lifecycle
events. -v and --verbose remain available when an explicit flag is useful.
Use --priced to exclude targets without pricing metadata, or --unpriced to
inspect exactly those targets whose pricing needs investigation. These options
cannot be combined.
health and contribute¶
Inspect local unified observations, or explicitly export aggregate-only public evidence:
basemode health
basemode health --verification
basemode contribute preview --since 2026-08-25T00:00:00Z
basemode contribute export --output contribution.json
basemode contribute release BUNDLE_ID
basemode contribute pr --repo OWNER/basemode-evidence
Preview, export, and PR submission work with existing stored observations; the
explicit command is the contribution consent boundary. --since and --until
take a plain date or any ISO-8601 timestamp, with or without a trailing Z,
and default to the last seven days. Windows may overlap freely: an export marks
the operations it counted, and later bundles skip them, so repeating a command
cannot contribute the same observations twice. release undoes an export that
was never submitted. Exports contain only
grouped counts, safe failure categories, and aggregate
performance/usage/cost measurements.
bench¶
Run each candidate strategy against a model and rank them by continuation quality. Makes real API calls — four short probes per strategy, a fraction of a cent for a full run. See Strategies for how scoring works.
| Option | Default | Description |
|---|---|---|
-s, --strategies |
system,prefill,few_shot |
Comma-separated strategies to compare |
-M, --max-tokens |
60 |
Max output tokens per probe |
-t, --temperature |
1.0 |
Sampling temperature (the one value every provider accepts) |
--samples |
false |
Print a sample continuation (or the provider error) per strategy |
--save |
false |
Pin the winning strategy for this model |
--json |
false |
Emit the ranking as JSON |
Exits 1 when no strategy produced a usable continuation — usually a missing
key or a model ID the provider doesn't recognize. Run with --samples to see
the underlying errors.
# Compare, then pin the winner
basemode bench kimi-k3 --samples
basemode bench kimi-k3 --save
# Drop the pin again
basemode strategies --unpin kimi-k3
Server¶
serve¶
Run an OpenAI-completions-compatible server (POST /v1/completions), backed by continue_text/branch_text. Requires the server extra: pip install 'basemode[server]'.
Set a compatible client's endpoint to
http://<host>:<port>/v1/completions. Requests accept model, prompt,
max_tokens, temperature, n, echo, and strategy. The server also
exposes GET /v1/models.
Responses are synchronous JSON, including when a request supplies stream;
SSE and logprobs are not supported. The endpoint works with clients such as
Tapestry Loom that accept the
classic completions format.
Configuration¶
keys¶
Manage persisted API keys (~/.config/basemode/auth.json).
default¶
Show/set/unset default model.
Setting a default resolves aliases and canonical provider/creator/model
names to the provider's catalog ID, preserving its spelling and case. Unknown
names are rejected with close-match suggestions; the previous default is kept.
Validation uses the local model catalog and makes no provider requests. Use
--force to save an unlisted model when the catalog has not caught up.