Jeden/Docs

CLI command

jeden token

Inspect the current model route and manage Jeden's optional private provider-token list.

Exact invocation#

Shell
jeden token [status|list|add LABEL --endpoint URL|remove ID] [--json]

Inputs and options#

  • Set JEDEN_MODEL_ENDPOINT to an OpenAI-compatible provider's base URL. A nonempty JEDEN_MODEL_KEY takes precedence over the stored list. Without a direct endpoint, model requests go to Stado's inference alternatives and Brama's own API to the route Stado names for it (see Other products); its signing secret and distinct bearer are read only from the process environment.
  • Both JEDEN_MODEL_ENDPOINT and the add LABEL --endpoint URL input must be HTTPS or loopback HTTP with no userinfo (even an empty @), query or fragment. An invalid direct endpoint is refused before a key or catalog request is sent. add reads the secret from standard input, never argv. Use the same base URL for both settings. remove ID takes the ID printed by list.
  • For example, with a provider key in $PROVIDER_KEY, run printf '%s\n' "$PROVIDER_KEY" | jeden token add personal --endpoint https://api.openai.com, then JEDEN_MODEL_ENDPOINT=https://api.openai.com jeden run 'Explain the current project' --model gpt-4o --model-only. Run jeden token list to get its ID and jeden token remove ID when it should no longer be used. The list is optional; a process with a nonempty JEDEN_MODEL_KEY uses that key instead.
  • Jeden Desktop's Settings → Model credentials screen calls the same token/status, token/add and token/remove RPC methods on its selected Jeden host. A missing or non-string parameter is invalid_params (jeden.token.parameter-missing, naming the method, the parameter and what the request held instead, never the key); an unknown token/* method is method_not_found (method-unknown); every refusal of the CLI is credential_error with the same sentence and its declaration as the error's data. Jeden runs no gateway of its own: subscriptions are served by the alternative Stado names for inference.
  • In the interactive terminal, the startup model picker and /model read the selected provider's catalog with the same stored-token rotation. A direct provider offers its concrete model IDs rather than Brama's virtual subscription routes. A catalog refusal names the provider operation and is not presented as an empty model list. The /setup picker and /setup status identify the direct route and its credential source without rendering the endpoint URL, which may contain private path segments. /setup validate prints the observed direct-provider route under model, not an absent brama probe; its optional no-key row is informational because anonymous providers may work.
  • The real provider qualification is node tests/model/tokens.mjs with JEDEN_BIN, JEDEN_TEST_SOURCE_REVISION, JEDEN_TEST_PROVIDER_ENDPOINT, JEDEN_TEST_MODEL, and two distinct live keys in JEDEN_TEST_PROVIDER_TOKEN_A and JEDEN_TEST_PROVIDER_TOKEN_B. It requires a clean committed checkout and a binary embedding that revision, isolates HOME and sessions inside the checkout's ignored build directory, removes Brama credentials from the exercised process, exercises a genuine provider refusal followed by both a model-only answer and a complete run with intake and acceptance inspection using stored keys, then a final all-keys-refused request. It retains the redacted command report and removes its isolated secrets.
  • The same journey adds and removes a token through the Desktop-facing RPC, verifies the persisted list through the CLI, and sends competing adds from separate RPC processes to require one saved ID and an actionable duplicate-label or transaction-contention refusal. A repeated sequential add specifically refuses the duplicate label. It sends successful and refused real model requests with JEDEN_MODEL_KEY to confirm neither falls back to or mutates the stored pool, and refuses Brama virtual model routes on the direct path. Its retained report redacts credentials and the provider endpoint from commands, output and RPC frames while keeping the endpoint digest.

Output and state effect#

The private ~/.jeden/model-tokens.sqlite3 file stores labeled secrets for subsequent calls. status and list never reveal them; JSON rows include id, label, endpoint, last selected state and last failure. Direct status reports keySource as environment, local-token-list, or none for that endpoint, not a declaration that an unrelated saved token works. Without a process key, each direct catalog or chat request selects the next stored key for its endpoint. With no key at all, Jeden sends an unauthenticated request; none is not a refusal if the provider accepts it, and a real catalog or chat response decides availability. A direct catalog that declares no revision is identified by the SHA-256 digest of its actual response body, not by the protocol version. A key refused by HTTP 401, 402, 403 or 429 before model output rotates to another untried key and retains the failed operation, status and redacted response. Buffered responses and individual streamed lines redact the selected key if the provider echoes it. A malformed optional response header on a rejected streamed attempt does not stop rotation before another key is tried; with no further key, the refusal retains the observed HTTP status and header cause. Exhaustion reports the last actual refusal. Without a direct provider, status reports route: stado with the order of Stado's inference alternatives, or Stado's declared refusal as routeRefusal; it reads no Brama signing secret or bearer and reports none.

Refusals and boundaries#

  • Every refusal is declared; jeden errors show jeden.token and jeden errors show jeden.token.store list them, and none names a key. jeden.token: words it does not take (words-unknown, exit 2, naming only a verb it knows and how many words follow, since a key placed there by mistake is never printed); a key typed at a terminal (key-on-terminal), not UTF-8 (key-not-text, naming the byte where it stops), unreadable (key-unread) or empty (key-empty); a blank (label-blank) or padded label (label-padded); an endpoint that is no URL (endpoint-unparsable), not HTTPS or loopback HTTP (endpoint-insecure), holding a user part before @ (endpoint-credentials, shown by scheme, host and port only) or a query or fragment (endpoint-suffixed), all exit 2; a label already stored (label-taken, naming its id) and an id the store does not hold (id-unknown, saying how many tokens it holds or that no store exists), exit 1. The refusals keep the phrases model endpoint must be HTTPS or loopback HTTP, without credentials, query or fragment, already exists and unknown token id. For an invalid JEDEN_MODEL_ENDPOINT or a non-Unicode direct endpoint or key, status remains an inspection: JSON reports a direct route with keySource: refused, a null endpoint and the declared routeRefusal, while text status, /setup, /model, the model doctor probe and Desktop show it without echoing credential bytes.
  • jeden.token.store, naming the directory or file, the step and what was found: ~/.jeden that is a link or no directory (directory-not-directory), cannot be described (directory-uninspectable), cannot be created (directory-uncreatable), belongs to another uid (directory-foreign), has a mode open to others (directory-shared, naming it) or cannot be closed (directory-unprotected); a store that cannot be described or created (store-uninspectable, store-uncreatable), is no file (store-not-file), is open to others (store-shared) or belongs to another uid (store-foreign); and SQLite's answers told apart by its result code: no database (store-unopenable), a database without the store's tables (store-schema-other), read-only or full (store-unwritable), a constraint (store-constraint), held by another process (store-busy, exit 69) and a row of another type (row-malformed). An invalid JEDEN_MODEL_ENDPOINT is jeden.model.route's endpoint-unparsable, endpoint-insecure, endpoint-credentials or endpoint-suffixed (the sentence begins reading the direct provider's endpoint from JEDEN_MODEL_ENDPOINT: model endpoint must be HTTPS or loopback HTTP …), a route variable that is not UTF-8 variable-not-unicode (its length and the byte where it stops, never its value), and a turn with no Stado and an empty store stand-in-absent. Tests: tests/token/store.mjs, tests/model/routes/route.mjs; the causes no local state provokes are in tests/untested-causes/searching/token.json.
  • When no direct endpoint is selected, status reports the route Stado gives: route: stado, keySource: not-needed, origin, and alternatives, Stado's inference alternatives in the order stado capabilities inference --json lists them; when Stado cannot be run, or its listing refuses, alternatives is null and routeRefusal holds Stado's declared jeden.alternatives refusal. Jeden reads no Brama signing secret or bearer for this route, so none is reported. Status remains a configuration inspection, not evidence that a model request has succeeded.
  • If a rejected provider response body cannot be read, the HTTP status and body-read cause are retained. Another stored key is tried before model output; exhaustion reports the actual failure rather than inventing a response body.
  • A Brama virtual model selected with a direct provider is refused by the model call and jeden doctor; select a concrete model ID from that provider's catalog.
  • A command line of the wrong form (an unknown command or option, a missing, unexpected or invalid argument, a missing confirmation) prints the error and the usage and exits 2; a refusal that retrying unchanged can help (a dependency down or not answering, a rate limit) exits 69; any other refusal or failure exits 1. A refusal a functionality declares ends with fix: … and cause: <operation>.<cause>, and jeden errors show <operation> lists every cause of that functionality.