Jeden/Docs

Command reference

The complete Jeden CLI.

Every command below is dispatched by the current Jeden binary. Each linked page gives the exact invocation, purpose, required inputs and options, output or state effect, and the refusal boundaries enforced by source.

Interactive root and global options#

Running jeden without a command opens the interactive terminal. --cwd path, --model name, --max-tokens n, --max-steps n, --allow-write, --allow-command, and --yolo configure that root invocation. --version/-V prints the compiled version and --help/-h prints usage. --help or -h after any subcommand prints that subcommand's usage lines and never runs it.

The compiled version names the source it was built from. A release build carries the version its release states in JEDEN_BUILD_VERSION; a tree Stado exported without Git carries <base>+commit.<commit>, the whole commit id from WISENT_SOURCE_COMMIT; a checkout carries <base>+dev.<commits>.<short-sha>, with .dirty when it holds uncommitted or untracked files. A checkout's version is taken again by every build after anything it names changes: a commit, amend or git pack-refs (Git's record of HEAD, the branch's ref, packed-refs and the index), or a change under rust, to Cargo.toml, Cargo.lock or build.rs. So two builds of one package version are told apart, and a build never names a commit it was not built from. A checkout Git cannot describe stops the build naming Git's answer and both variables.

Unknown commands and unknown global options fail instead of falling through. Environment files load from the selected workspace before dispatched commands run.

The prompt, approval questions and running turns share one terminal event stream. A key press, resize, worker output or worker completion triggers the next update; the busy indicator does not advance on a timer. Esc or Ctrl-C during a turn announces cancellation. Foreground commands and the external editor take ownership of stdin after the event reader is released.

A terminal read failure reports terminal event read failed: <cause>; a closed stream reports terminal event stream closed. A rendering or input error cancels the running turn and releases queued approval replies before joining its worker. A worker panic reports Turn thread panicked. rather than leaving the prompt waiting for another key.

Interactive
jeden [--cwd path] [--model name] [--max-tokens n] [--allow-write] [--allow-command] [--yolo] [--max-steps n]

Refusals of the command line#

Reading the command line is the functionality jeden.invocation; jeden errors show jeden.invocation prints the causes below with their tests. Each refusal is printed before anything runs, then fix: … and the cause's id; every one but the last also prints the usage and exits 2.

  • command-unknown: reading the command `<word>`: unknown command: <word>; jeden has no command by that name, observed: every command there is. Fix: run one of the commands the usage lists.
  • option-unknown: reading the option `<option>` of `jeden <command>`: unknown option: <option>; neither jeden nor `<command>` reads an option by that name. Fix: drop it or spell an option the usage lists.
  • option-value-missing: reading the value of <option>: <option> requires a value, and the command line ends at it. Fix: write the value after it.
  • bound-not-whole: reading --max-steps <value>: --max-steps must be an integer: a whole number from 0 to 4294967295 (also --max-tokens), observed: the word read. Fix: give a whole number.
  • pursue-modes-exclusive: choosing the pursue mode <second>: pursue request, status, state and resume modes are mutually exclusive, and <first> already chose one. Fix: keep one of --request-file, --status, --state and --resume-run.
  • pursue-objective-with-mode: reading the pursue objective `<words>`: a machine pursuit request cannot also contain a positional objective. Fix: drop the objective words or the mode option.
  • task-missing: reading the task of `jeden run`: run requires a task, and the command line gives none (also pursue). Fix: quote the task after the command.
  • working-directory-unreadable: reading the directory `jeden <command>` runs in: the current directory cannot be read, and --cwd names no other, observed: what the system answered; exit 1, without the usage. Fix: run Jeden from a directory that exists, or name one with --cwd. jeden --version reads no directory.

Finding the home#

Every user file of Jeden is under ~/.jeden: the environment file, the configuration, the sessions and the durable state's own SQLite file. The home is HOME when it is set and not empty, else the home the user database records for this user. Finding it is the functionality jeden.home; every command but --version, --help and errors runs it before it reads a user file, and --help and errors answer from what is compiled in, so neither a missing home nor a broken configuration stops them.

  • home-unknown: locating the home directory Jeden keeps its user files in (~/.jeden): HOME is unset or empty, and the user database records no home directory for this user, observed: whether HOME is unset or empty; exit 1. Fix: set HOME to this user's home directory, or record one for this user in the user database. It is listed in tests/untested-causes.json: every account that can run a test has a home recorded, so unsetting HOME does not provoke it.

Sessions and artifacts#

  • jeden import — Preserve sessions of another harness — their conversation history and interrupted requests — in native Jeden ledgers without executing work.
  • jeden sessions — List locally stored Jeden session identifiers.
  • jeden sessions search — Search durable session event payloads for a case-insensitive text fragment.
  • jeden resume — Seed a fresh Jeden session with the conversation turns from a recorded session and optionally continue it immediately.
  • jeden show — Print one durable session: each event under its own heading, or the whole record as JSON.
  • jeden export — Write a recorded session to a file as JSON, HTML, or Markdown. Printing a session is jeden show.
  • jeden artifacts — List files in one session's artifact directory.
  • jeden artifact — Read one UTF-8 session artifact or copy it to a requested output file.

Run and automation#

  • jeden run — Run one concrete agent task through a durable Jeden conversation.
  • jeden pursue — Turn a rough objective into a source-grounded autonomous contract, execution, independent review, verdict, and receipt.
  • jeden rpc — Serve Jeden's newline-delimited JSON RPC interface on standard input and output.
  • jeden headless — Serve the multi-tenant Jeden RPC service over a TLS listener where each client proves itself with a client certificate or with its Wisent identity.
  • jeden acp — Serve Jeden as an Agent Client Protocol agent over standard input and output.
  • jeden relay serve — Run the encrypted collaboration-room relay used by interactive collaboration commands.
  • jeden hillclimb — Improve a repository, or every repository of an organization, round after round without end: choose the next improvement, pursue it to an independently accepted result, record it, and choose again.

Runtime and operations#

  • jeden tools — Inspect the currently visible and executable Jeden tool registry.
  • jeden update — Transactionally install a signed Jeden release and verify the activated binary before committing it.
  • jeden doctor — Probe the live health of Jeden's configured runtime dependencies and local subsystems.
  • jeden conformance — Evaluate Jeden's canonical completion areas, production scopes, evidence, and UI-honesty contract.
  • jeden capabilities — Inspect Jeden's atomic capability-discovery and health snapshot.
  • jeden token — Inspect the current model route and manage Jeden's optional private provider-token list.
  • jeden token status — Inspect the selected model route and credential source without revealing keys.
  • jeden token list — List the private provider-token metadata, never the secrets.
  • jeden token add — Persist one labeled provider key for a specific direct endpoint.
  • jeden token remove — Delete exactly one saved provider key by its listed ID.
  • jeden chat-memory — Read an agent's never-ending chat, laid out as the operator's OptChat design — the append-only log of every message of every session of the chat, the binary tree of one-line summaries over it, and the view each turn is given, with the same zoom(id, n) and date(id) the model has through recall_conversation — and bring an earlier session into a chat.
  • jeden stats — Show local usage, quota, and session totals or serve the same snapshot as a loopback dashboard.
  • jeden gallery — Render the TUI component gallery under the effective theme or every compiled-in preset.
  • jeden copy — Hand an exact payload to the operator's clipboard from outside an interactive session, or check it is still there.

Configuration#

  • jeden workspace — Inspect, validate, adopt or forget an existing local repository as Jeden's default workspace.
  • jeden workspace status — Show the currently adopted workspace and the existing sessions associated with it.
  • jeden workspace forget — Stop using the adopted workspace as the default, the inverse of adopt.
  • jeden workspace discover — Validate an existing workspace and preview the state Jeden would adopt.
  • jeden workspace adopt — Persist an existing local repository as the default workspace used by the next Jeden task.
  • jeden config — Inspect and change Jeden's schema-backed user configuration.
  • jeden contracts — Print Jeden's contracts as one text, and install them into a file another program reads as a system prompt.
  • jeden config list — List every schema-backed setting and its effective value.
  • jeden config path — Print the writable user configuration file path.
  • jeden config get — Read one effective schema-backed setting.
  • jeden config set — Validate and persist one user configuration setting.
  • jeden config reset — Persist one setting's schema default into the user configuration.
  • jeden config unset — Remove one setting from the user configuration, so the file says nothing about it again.

Shell completions#

Roadmap#

GitHub star request#

  • jeden star — Read, dismiss or restart the request for a GitHub star that Jeden makes once, after the fifth successful prompt.

Retained tasks#

  • jeden todo — Inspect and control every retained user request and its verified task state.
  • jeden todo list — Read retained requests, tasks, acceptance requirements and completion evidence.
  • jeden todo add — Record a user request without executing it or inventing its acceptance result.
  • jeden todo pause — Pause retained work without losing it.
  • jeden todo resume — Make paused retained work eligible to run again.
  • jeden todo cancel — Withdraw exactly the work the operator selected.
  • jeden todo defect — Record a defect and reopen its original task for repair.
  • jeden todo answer — Answer, from a blocked task, the ask it waits on.
  • jeden todo continue — Inspect previous results and continue retained work without adding a synthetic user request.

Operator asks#

  • jeden asks — Read everything Jeden asked of you, in every session, and what you answered.
  • jeden asks list — List every ask, newest first, with its status and your answer.
  • jeden asks show — Show one ask with every place it was asked.
  • jeden asks answer — Answer an ask once, for every task waiting on it.

Context advisor#

  • jeden context — Ask the context advisor what to read for a task instead of searching for it.
  • jeden context recommend — Return ranked locators for a task, with the state of every source that answered.
  • jeden context prompt — Print exactly the recommendation block a turn would append for this task.
  • jeden context sources — Report what each context source is configured to be and whether it answers now.

Failures#

  • jeden errors — Print every way each Jeden functionality can fail: what failed, why, the state the refusal shows, what fixes it, its code, its exit status and the test that provokes it.