Olenji command and model reference

Companion to the user guide · Inspected 1.0.0 development build · 28 October 2026

Use this reference for exact commands, model IDs, settings, and agent request formats. For ordinary tasks and plain-language explanations, start with the user guide.

This reference describes the same inspected source as the user guide. Names and model counts are not substitutes for checking whether a feature runs on your computer.

CLI command directoryContents

Every command begins with olenji. Use olenji COMMAND --help for all options in your installed build. --json requests structured output; readable exports write their document bytes rather than a normal command-result wrapper.

The complete option definitions are also stored in reference-inventory.json in this bundle. They are extracted from the parser, not maintained as a second hand-written parser.

MCP tool directoryContents

These are the tools available to a connected agent. A tool's input schema defines its accepted fields. CLI operations without a dedicated MCP tool remain available through the terminal or local API.

Model catalogContents

An entry is an exact model size or conversion, not necessarily a unique model family. Each entry needs a compatible host and runtime. Native model streaming capability does not prove that Olenji uses a continuous streaming decoder for that entry.

The FV (FluidVoice) column identifies the dated 17-entry comparison set. The catalog's terms and sources are recorded in the machine-readable inventory. Inspect the installed app for actual readiness:

olenji models inspect MODEL_ID --json

Model profilesContents

A profile is a fixed selection for installation. It is not automatic routing between models.

olenji models install --profile recommended --json
olenji models plan-install --profile fluidvoice-parity --compatible-only --json
olenji models parity --json

Inspect skipped entries. A successful compatible-only installation is not a successful installation of the entire profile. Apple-only entries remain Apple-only.

Saved settingsContents

Omitted options use the saved defaults shown here. They are values in the reviewed source, not recommendations for every machine.

Read or change them through the CLI:

olenji config get --json
olenji config set default_translation_language tr --json
olenji config set ui_layout bilingual --json
olenji config set default_model faster-whisper.small --json

Changing default_model does not install it. Changes affect subsequent operations; they do not silently replace a running session's model. max_parallel_jobs takes effect after service restart. Explicit request options override defaults.

Session-level metadata permits retain_audio, translation_language, diarize, local_only, tags, auto_translate, translation_provider, and translation_model. Updating a diarization preference is not retroactive speaker processing; use refinement with retained audio to reprocess a completed recording.

Browser file-upload preference: the upload form now starts with the saved retain_audio value, just as the live form does. An explicit choice in the upload form takes precedence for that file.

Recognition settingsContents

Leave these unset unless you have a reason to tune them. More threads or a larger model do not guarantee better live performance.

olenji transcribe interview.wav --model faster-whisper.tiny --device cpu --compute-type int8 --cpu-threads 2

Use the individual flags or one --inference JSON object, not both. Supported thread values are 1 through 64. device accepts cpu or cuda; the actual engine checks availability. A requested backend does not install its drivers.

native_backend accepts auto, cpu, metal, vulkan, cpu_accel, cuda, or rocm, depending on the native build. Unsupported combinations fail; they should not be presented as tested accelerators.

The pinned Qwen3 and Voxtral adapters use automatic language detection. Apple Speech and the Cohere conversion need an explicit supported recognition language. Not every model accepts the same recognition controls.

Refinement inherits compatible prior settings when appropriate. A supplied inference object replaces them. --inference '{}' requests the backend defaults rather than merging selected fields.

Edit and translation examplesContents

Read the actual IDs and revisions before editing. The files in examples/ are templates, not requests that work unchanged against any session.

Read a small window

Save this as window.json:

{
  "limit": 50,
  "target_language": "tr",
  "committed_only": true
}

olenji sessions window SESSION_ID --query @window.json --json

Without offset, the result starts near the newest turns. Use "offset": 0 to start at the beginning. window_ids identifies the requested rows; additional source rows can be included to keep multi-turn translations understandable. Use the returned paging values rather than counting those extra rows as new page entries.

Submit a translation from an agent

Save this as translations.json and replace the source reference with a real completed turn:

{
  "translations": [
    {
      "source_refs": [{"segment_id": "SEGMENT_ID", "revision": 1}],
      "target_language": "tr",
      "text": "Toplantı saat üçte başlıyor.",
      "producer": {"kind": "external_agent", "name": "my-agent"}
    }
  ]
}

olenji translations put SESSION_ID --file translations.json --json

The Turkish sentence is an example, not the correct translation for every source. Include every source reference when one sentence spans several turns. Read existing translations first. Use producer.kind: "human" only for a genuine human correction.

A batch accepts up to 500 translations; a translation accepts up to 100 source references. The smaller HTTP request-size limit still applies. The CLI permits up to 8 MiB of JSON input and 256 nested containers, but that is not permission to exceed the service's 2 MiB ordinary request limit.

Merge adjacent source turns

Save this as merge.json, using real current revisions:

{
  "segment_ids": ["SEGMENT_A", "SEGMENT_B"],
  "expected_revisions": {"SEGMENT_A": 1, "SEGMENT_B": 2},
  "text": "The combined source text."
}

olenji segments merge SESSION_ID --file merge.json --json

The turns must be adjacent source turns. Search results that happen to appear next to each other are not sufficient.

Configure a bilingual browser view

Save this as view.json:

{
  "layout": "bilingual",
  "target_language": "tr",
  "typography": {"original_scale": 1.0, "translation_scale": 1.3},
  "original_visible": true,
  "follow": "live"
}

olenji ui list --json
olenji ui configure VIEW_ID --config @view.json --wait-applied 5 --json

The result distinguishes requested settings from a connected view applying them. Applied settings do not guarantee visibility, focus, microphone permission, or audible playback.

Translation service setupContents

A provider must already serve a compatible text model. Olenji's speech-model installer does not download or start that text model.

olenji providers add local --base-url http://127.0.0.1:11434/v1 --model TEXT_MODEL_ID
olenji config set default_provider local
olenji translate SESSION_ID --provider local --to tr --json

Replace the example address and model with your actual local service. Online providers require HTTPS. Use --api-key-env VARIABLE_NAME or --api-key-stdin to avoid putting the key literally in the command history. Provider files remain private local files, not an encrypted secrets vault.

Changing the configured service address discards the stored key unless you explicitly supply a replacement. Provider lists omit the key itself.

To permit an online provider for one session, obtain the user's agreement and save this as allow-online-text.json:

{"local_only": false}

olenji sessions configure SESSION_ID --metadata @allow-online-text.json --json

This permits online processing for the session, not only one translation request. An online text provider receives transcript text. Apple Legacy can also use network recognition when this restriction is removed. It does not make an external agent private or audit another service's networking.

For the inspected source, automatic recovery uses an initial attempt and at most three retries, with 30-, 60-, and 120-second delays. The retry deadline survives service restart. Permanent or exhausted failures stay blocked until relevant repair or explicit reconfiguration. A separate manual translation request has its own job.

Disabling automatic work and canceling a currently owned job are distinct actions. Do not use unrelated tag edits as a retry mechanism. Source commits and scheduler notification are separate steps in this inspected build; later conversation-described transactional recovery changes are not verified here.

Local API and agent contractsContents

Submit a local file

A local path request uses POST /api/transcribe/path. The service must be able to read that path. Save this as file-request.json:

{
  "path": "/absolute/path/interview.mp4",
  "model_id": "faster-whisper.tiny",
  "language": "en",
  "diarize": false,
  "retain_audio": true
}

olenji api POST /api/transcribe/path --body @file-request.json --json

For byte uploads, use multipart POST /api/transcribe with the file field and the supported form fields. File-path requests and uploads are different routes. Neither is a website-video downloader.

Use the installed schema for exact operations:

olenji schema --json

Direct HTTP callers need the local bearer token or a paired browser session. Never paste api.token into a public issue. The CLI and MCP handle their local connection; callers should not bypass authentication or expose the service publicly.

Read metadata without the whole transcript

In this inspected build, CLI sessions get and sessions snapshot return the full record. Use the MCP olenji_session tool or the metadata endpoint for a small result:

olenji api GET /api/sessions/SESSION_ID/metadata --json

Use session windows or paginated segments for transcript text. If a cursor-consistent page request reports a change, restart that read rather than combining mismatched pages.

Follow changes and retry work

olenji events SESSION_ID --after 0 --limit 100 --committed-only --json
olenji events SESSION_ID --follow --committed-only --jsonl
olenji jobs wait JOB_ID --wait-timeout 30 --json

The returned cursor records which changes have been consumed. Following events is not a substitute for retaining the current source revision when editing. A reset response means the saved position is no longer valid and a fresh read is needed.

A wait timeout ends observation, not the underlying job. Keep the returned ID and inspect it rather than automatically creating duplicate work. Supported starts accept --idempotency-key; reuse the same key and arguments only when retrying the same intended request.

Successful ordinary responses use ok, schema_version, and data. Failures include an error code, message, details, and retryability. A success envelope for job admission is not proof that the job later completed. Export bytes and MCP messages have their own output formats.

Reviewed build and evidenceContents

The source branch reviewed on 28 October 2026 descends from the 5,374,566-byte olenji-1.0.0.zip archive identified below. The review uses the supplied olenji-source-update.zip, then applies the matching changes documented in this edition. The original archive has SHA-256:

7543479f38124b183aefd24f07522a4fde42664103241e0bda1ffa1ac07c304c

This branch preserves offline help and the upload audio-retention fix. The current review separates shared helpers from service startup, validates translation addresses consistently, enables repair or removal of damaged provider entries, preserves created views when browser launch fails, and fixes search highlighting of literal text. Command examples and request templates are checked against the actual parser and schemas. Other changes described in conversation but absent from the supplied source are not implied. The unchanged 1.0.0 version string is not a unique build identity; use the source fingerprints and review report.

source-provenance.json identifies reviewed files. reference-inventory.json records complete commands, settings, model records, and tool schemas. The verifier checks these without changing the expected fingerprints. Review actual source changes before updating them.

The evidence separates parser checks, schema validation, source-backed behavior tests, and presentation checks. It does not claim new speech-recognition, physical capture, GPU, Mac, or Windows validation.

The upload-default patch is applied in this source branch. Its real-browser test checks the selected preference and the submitted form data; it does not test speech recognition or audio deletion. See MAINTAINING_DOCUMENTATION.md for repeatable checks and future updates.