Jeden/Docs

CLI command

jeden run

Run one concrete agent task through a durable Jeden conversation.

Exact invocation#

Shell
jeden run "task" [--json] [--model-only] [--cwd path] [--model name] [--max-tokens n] [--allow-write] [--allow-command] [--yolo] [--max-steps n] [--resume-session id-or-dir]

Inputs and options#

  • Required: a non-empty task after run.
  • --cwd, --model, --max-tokens, and --max-steps select the workspace, route, response budget, and step bound.
  • --allow-write and --allow-command grant those tool tiers; --yolo grants both. --model-only suppresses tools and --json wraps local slash-command output where supported.
  • --resume-session takes a session id, as jeden sessions lists it, or its directory. The run continues that session — its history, transcript and chat memory — instead of starting one, and a one-shot session command (/checkpoint, /rewind, /compact, /handoff, /context) acts on it; without it a session command acts on the workspace's last recorded session. Interactive jeden --resume-session <id-or-dir> loads the session's turns into a new conversation the same way. While a Jeden process records a session it holds that session's transcript.jsonl open for appending, which is how Oko tells which session a running Jeden is; JEDEN_BIN=… JEDEN_TEST_SOURCE_REVISION=… node tests/sessions/held/transcript.mjs requires a real jeden rpc to hold it open for writing once a session opens and to hold it no longer once the session is disposed (no model is called; the report stays under .build/held-transcript).

Output and state effect#

Records the original request durably before model access, then records acceptance requirements in a separate read-only conversation before execution. Every proposed final is independently checked against all retained tasks and original requests; incomplete actionable work continues automatically. The returned JSON includes completion with status, revision, requests, tasks and blockers. Model-only calls and Pursuit's independently owned stage reviews keep their own output contracts.

Refusals and boundaries#

  • A missing task is refused exactly as run requires a task.
  • The session mode commands are jeden.modes (jeden errors show jeden.modes, tests/modes/commands.mjs), their words read whole before the mode state changes. Exit 2: /loop with a count past 64 bits (loop-count-too-large) or a duration the clock cannot count (loop-duration-uncountable; units are ms, s, m and h, minutes and hours counted through Duration's own factors, and an amount whose seconds do not fit is refused naming its unit), /fast tier without a tier, an unknown /fast verb, /force without a tool, and /approval mode or /approval <tool> without, or with an unknown, mode or policy, each naming the choices. Exit 1: /force of a tool the workspace does not make visible (force-tool-unavailable, naming the visible ones) and /branch, /fork, /rebuild, /drop, /rename or /move in a one-shot run (interactive-only). A mode state of the wrong shape (jeden.state.file.mode-state-invalid, naming the field) is refused when Jeden starts and by every command and turn that reads it, never read as every mode off; the status line then shows the refusal's first line.
  • /payment-method setup, /billing policy get|set|reset and /subscriptions list|status|disable|purchase|renew are jeden.billing.command (tests/billing/command.mjs), read whole before Weles is asked; each refusal exits 2 naming every form: verb-unknown (also /billing, /subscriptions or /payment-method alone, which printed a usage and exited 0), argument-unexpected, option-repeated, option-valueless, option-missing, option-unknown, number-invalid, list-empty, and for a policy renewal-without-purchase, caps-invalid, period-unknown and policy-unbounded.
  • /goal and /guided-goal are jeden.goal and /advisor is jeden.advisor (tests/modes/steering.mjs). Exit 2: an objective missing after /goal set or /guided-goal, a budget that is no positive number, /goal auto without on or off, an unknown /advisor verb and /advisor configure without a route. Exit 1: /goal resume with no objective set (nothing-to-resume), /advisor dump before any review (notes-absent) and a last review without text (review-textless, which /advisor dump raw shows whole).
  • A --resume-session that names no session is refused naming the file it could not read (cannot read <dir>/state.json: …; interactively --resume-session names no session: <dir> does not exist). A session command with neither a named nor a recorded last session is jeden.session.find.last-session-unrecorded (… no session is recorded for <cwd> yet, fix: name one with --resume-session <id-or-path>, or run a task first), exit 1; a recorded last session that is gone is session-not-found.
  • A missing value for a valued option is refused (for example --model requires a value); non-integer token or step bounds are refused.
  • Model work fails closed when required router configuration or credentials are absent, and write or command tools remain approval-gated unless their tier was granted.
  • An explicit direct provider endpoint must be HTTPS or loopback HTTP, without embedded credentials, query or fragment. Jeden refuses JEDEN_MODEL_ENDPOINT before sending a catalog credential to any other address; a process-owned key does not override this safety check.
  • Completion intake and acceptance inspections read the selected route's model catalog for its declared output ceiling, using the same direct-provider token list and rotation as a run when JEDEN_MODEL_KEY is unset. An unreadable catalog, unresolved model or ceiling too large for Jeden refuses the inspection with its cause; an entry declaring no ceiling uses the provider's own limit.
  • On macOS, a missing task sandbox helper is reported as jeden-sandbox-helper is not installed beside the Jeden executable; build and code-sign it or set JEDEN_TASK_SANDBOX_HELPER. Install the complete release, keeping its signed jeden-sandbox-helper beside jeden; the release SBOM and provenance identify both executables.
  • After a request is captured, a preparation failure is retained in the session transcript as run_error, with operation: prepare_turn and the original failure message. Inspect it with jeden show <session-id>. The same conversation path serves CLI and RPC; a recorded refusal is not successful execution and does not complete the retained request. Failures before conversation creation are not covered by this event. If writing the event also fails, the returned error names both failures.
  • A non-rate-limit HTTP failure from Brama includes its status, the requested API path, and the quoted response body. An empty quoted body means that the upstream server supplied no error detail; it is not a model answer. The CLI and RPC report the same failure.
  • A model transport failure names the failed operation, the selected /v1/chat/completions endpoint and its retained origin: a direct provider selected by JEDEN_MODEL_ENDPOINT, or the provider in Jeden's token store standing in. Streaming failures retain the original error class, response body or transport cause and whether output was already visible; cancellation remains cancellation. A closed connection without an HTTP response does not establish that a subscription is exhausted. CLI and RPC-backed graphical conversations receive the same cause.
  • An answer that is not an action of the protocol is jeden.model.answer (jeden errors show jeden.model.answer, tests/model/answer.mjs), and that refusal is what the model is shown when it is asked to correct its answer: an empty answer (answer-empty), prose where an object is needed (answer-prose; a turn takes prose as its final answer), an answer that stopped mid-JSON inside a string (answer-string-open) or with brackets open (answer-brackets-open, naming how many), an object that is not JSON (answer-not-json, with its line and column), no action (action-missing, naming the object's keys), an unknown action (action-unknown), a final or message without text (final-textless, message-textless), a tool call without a name or with input that is no object (tool-unnamed, tool-input-other, naming tools[N]) and a tools answer without a list or with an empty one (tools-missing, tools-empty). A turn whose same answer returns after correction ends with that refusal and the context: line the same failure recurred after correction; an answer cut by the output budget adds the answer was cut off by the output budget of N tokens. Whether an answer stopped mid-JSON is read from the refusal's declaration, never from its words.
  • Through Stado's inference alternatives (Stado installed, no JEDEN_MODEL_ENDPOINT) each request is handed to stado capabilities call inference --consumer jeden --json. When no alternative answers, the turn's refusal is Stado's own sentence: no inference alternative answers jeden: brama at …: <cause>; attestation at …: no statement answers request <sha> yet; read it with `stado capabilities attestation show inference --consumer jeden <sha>` and answer it with `stado capabilities attestation record …`. Brama's own HTTP refusal of the request is reported with its status and body. A Stado that cannot start is jeden.alternatives.stado-unstartable; one that prints neither an answer nor its failure envelope is refused naming the command and what it printed. The CLI, the durable session's run_error and the RPC prompt error and notification carry the same text.
  • If the model request fails and recording its route result or run_error also fails, the returned refusal preserves the original model cause and names the failed recording event with its filesystem cause. Failed context recovery likewise retains the initiating model failure and the recovery failure; if recording auto_compaction_error fails too, all three remain visible. A refused auto_continue write does not report a successful recovery. CLI, terminal and RPC-backed graphical conversations share this error propagation; a missing durable event is not evidence that the original request succeeded.
  • Session recorder initialization failures identify the operation and exact artifact: creating the session's artifacts directory, opening transcript.jsonl for append, or encoding/writing state.json. Filesystem refusals retain the actual operating-system cause. The same recorder serves CLI and RPC-backed conversations; an initialization refusal does not mean a model request ran.
  • When real tests are authorized, node tests/model/credentials/alternative.mjs runs the Stado route through the actual CLI and RPC interface in an isolated home. Supply JEDEN_BIN, JEDEN_TEST_SOURCE_REVISION (the clean checkout's HEAD), JEDEN_TEST_STADO (a Stado with capabilities call) and JEDEN_TEST_MODEL. It checks that jeden doctor --json names Stado's order, that jeden run is refused with Stado's sentence and that the refusal stays in the exported session, answers the kept request with stado capabilities attestation record and checks the same turn is then served by that statement, and checks the RPC prompt error and notification. Commands, exit statuses, raw RPC frames and exports are kept in the run's report.json.
  • An answer that arrives cut off or unreadable is recorded as a contract_violation with rule: model-answer. The exact refusal returns to the model while observed failures change and the caller's --max-steps permits continuation. Repeating the same malformed answer or the same provider cut-off cause ends the invocation with repeatedFailure: true and the original cause; there is no fixed answer-correction count. A caller-limit refusal also retains its cause, and neither refusal completes the retained request. If recording a first-response cut-off or malformed-answer correction fails, the returned refusal retains the initiating provider or parsing cause alongside the answer-recovery failure and its underlying recording cause; CLI and RPC-backed conversations use the same path.
  • /login, /logout, /refresh and /settings are jeden.auth; jeden errors show jeden.auth prints every cause with its test (tests/auth/login.mjs). Exit 2: provider-invalid (a provider that is no lowercase name) and account-invalid (account id or provider is required), both before Weles is asked, and answer-unknown (an answer to a waiting sign-in run that is none of the offered ones). Exit 1: provider-unregistered (provider `X` is not registered with Weles, observed: the providers it advertises, which the weles program names in weles login --help), account-unmatched (no Weles account matches `X`, observed: the accounts it keeps), input-unavailable (a sign-in question no person can answer here, such as /login apple with nothing on standard input), sign-in-failed (weles login --run answered ok: false) and sign-in-cancelled. Weles is the browser-automation alternative Stado names for jeden: its HTTP API at a directory route, or the weles program run with the verbs its CLI documents (/logout and /refresh run weles accounts logout|refresh for the account weles accounts list names), whose refusals are jeden.weles causes; when none can be spoken to, the refusal is the jeden.alternatives cause (see Other products). A Weles step that fails keeps Weles's own answer, and either names the step on a context: line.
  • 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.