CLI command
jeden token
Inspect the current model route and manage Jeden's optional private provider-token list.
Exact invocation#
jeden token [status|list|add LABEL --endpoint URL|remove ID] [--json]Inputs and options#
- Set
JEDEN_MODEL_ENDPOINTto an OpenAI-compatible provider's base URL. A nonemptyJEDEN_MODEL_KEYtakes 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_ENDPOINTand theadd LABEL --endpoint URLinput 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.addreads the secret from standard input, never argv. Use the same base URL for both settings.remove IDtakes the ID printed bylist. - For example, with a provider key in
$PROVIDER_KEY, runprintf '%s\n' "$PROVIDER_KEY" | jeden token add personal --endpoint https://api.openai.com, thenJEDEN_MODEL_ENDPOINT=https://api.openai.com jeden run 'Explain the current project' --model gpt-4o --model-only. Runjeden token listto get its ID andjeden token remove IDwhen it should no longer be used. The list is optional; a process with a nonemptyJEDEN_MODEL_KEYuses that key instead. - Jeden Desktop's Settings → Model credentials screen calls the same
token/status,token/addandtoken/removeRPC methods on its selected Jeden host. A missing or non-string parameter isinvalid_params(jeden.token.parameter-missing, naming the method, the parameter and what the request held instead, never the key); an unknowntoken/*method ismethod_not_found(method-unknown); every refusal of the CLI iscredential_errorwith 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
/modelread 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/setuppicker and/setup statusidentify the direct route and its credential source without rendering the endpoint URL, which may contain private path segments./setup validateprints the observed direct-provider route undermodel, not an absentbramaprobe; its optional no-key row is informational because anonymous providers may work. - The real provider qualification is
node tests/model/tokens.mjswithJEDEN_BIN,JEDEN_TEST_SOURCE_REVISION,JEDEN_TEST_PROVIDER_ENDPOINT,JEDEN_TEST_MODEL, and two distinct live keys inJEDEN_TEST_PROVIDER_TOKEN_AandJEDEN_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_KEYto 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.tokenandjeden errors show jeden.token.storelist 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 phrasesmodel endpoint must be HTTPS or loopback HTTP, without credentials, query or fragment,already existsandunknown token id. For an invalidJEDEN_MODEL_ENDPOINTor a non-Unicode direct endpoint or key, status remains an inspection: JSON reports a direct route withkeySource: refused, a null endpoint and the declaredrouteRefusal, 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:~/.jedenthat 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 invalidJEDEN_MODEL_ENDPOINTisjeden.model.route'sendpoint-unparsable,endpoint-insecure,endpoint-credentialsorendpoint-suffixed(the sentence beginsreading the direct provider's endpoint from JEDEN_MODEL_ENDPOINT: model endpoint must be HTTPS or loopback HTTP …), a route variable that is not UTF-8variable-not-unicode(its length and the byte where it stops, never its value), and a turn with no Stado and an empty storestand-in-absent. Tests:tests/token/store.mjs,tests/model/routes/route.mjs; the causes no local state provokes are intests/untested-causes/searching/token.json.- When no direct endpoint is selected,
statusreports the route Stado gives:route: stado,keySource: not-needed,origin, andalternatives, Stado's inference alternatives in the orderstado capabilities inference --jsonlists them; when Stado cannot be run, or its listing refuses,alternativesis null androuteRefusalholds Stado's declaredjeden.alternativesrefusal. 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) exits69; any other refusal or failure exits1. A refusal a functionality declares ends withfix: …andcause: <operation>.<cause>, andjeden errors show <operation>lists every cause of that functionality.