Olenji command and model reference

Companion to the user guide · Version 1.2.1 · 1 November 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.

Contents

1. CLI command directory
2. Passive environment advice
3. MCP tool directory
4. Model catalog
5. Model profiles
6. Saved settings
7. Recognition settings
8. Edit and translation examples
9. Translation service setup
10. Local API and agent contracts
11. Reviewed build and evidence

CLI command directory

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.

Passive environment advice

This interface is available from 1.1.0 across the Python, npm and direct-download routes. olenji environment --json and olenji_environment use the same passive report. The agent decides how to use it under the user's request and the host's permissions. Advice does not authorize an operation, replace the task or establish user-side access.

Context records what the caller declares. It does not test audio or file access, grant permission, identify the user's computer, or prove that a browser is visible. Process facts describe the process answering the request; operating-system or remote-session hints are not proof of the LLM's location or the user's device relationship. Invalid tasks, values and unknown context fields are rejected.

The returned contract_version is 1.0; this is independent of application_version. observed_at is a UTC observation time. authority marks the report advisory. runtime_host describes the reporting process, including interface (cli, mcp, service or direct python), OS, architecture, Python, CPU count and dependency executable-presence booleans. architecture_source records how the architecture was obtained; on Windows it is a canonical, unverified environment hint or unknown. Windows release information is numeric and obtained without launching a shell. facts_note explains those limits. CPU count is a logical-host observation, not an allocation or container-quota guarantee; it is null if undetermined. Unavailable OS facts remain unknown. hints carries limited SSH/container/display indicators with their interpretation. The report does not expose raw environment values, usernames, hostname, credentials, device lists or executable/workspace paths.

caller_reported retains normalized context and its declared provenance. unverified keeps audio capture, microphone/system-audio permission, model readiness, browser reachability and the user's device unknown. recommendation provides a route, reason, at most three next steps, a concise user message and a handoff prompt where applicable; boundaries explains its limits. Hints do not select the route or turn declared context into a verified fact. Invalid input returns INVALID_ARGUMENT without echoing the supplied values.

The standalone CLI path runs before workspace setup and performs no service request, network operation, device/model probe, recording, job, download or browser launch. The MCP tool is passive too, while starting mcp serve retains its existing workspace setup. Use doctor or olenji_capabilities separately for heavier service readiness; enumerated source availability still does not prove granted permission or incoming audio. The doctor's local_only value is a workspace default; inspect the selected session before relying on its provider policy.

Source discovery labels its evidence as scope:service_host and availability:adapter_or_prerequisites; permissions and audio flow are not_checked, and the user-device relationship is unknown. Existing available booleans keep their original prerequisite/enumeration meaning. MCP initialization supplies short advisory discovery text; the complete conditional workflow is available through olenji://agent-guide when the agent needs it.

For a supplied recording accessible to an authorized remote environment, use that environment and return a file or artifact. For live audio unavailable there, give a concise local-agent handoff. Unknown access calls for a targeted check, not an automatic platform switch. Text-only translation requires no speech model or audio capture. The agent instructions describe the short user-facing route.

MCP tool directory

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 catalog

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

These eight new choices are offline-only, capped at one hour of normalized audio and independently implemented from public ONNX/Sherpa contracts. They do not establish OVE Core ML output equivalence or measured quality for every recording. Inspect exact immutable artifacts, terms, speaker_presets, live_supported and compatibility before installation. Windows ARM64 cannot use the current SOXR-based ONNX stack; supported x64 Python or the Sherpa route is an alternative. Native foreign-OS execution remains separate from binary availability.

Model profiles

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 settings

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 settings

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 examples

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 setup

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 contracts

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 evidence

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. Earlier development archives shared the 1.0.0 version string, so their exact identity still requires the original source fingerprints and review report. The 31 October 1.0.2 release uses PyPI olenji and npm @batikanor/olenji, with coordinated versioned artifacts and unchanged command, tool, model and schema contracts. Published PyPI 1.0.0 and both 1.0.1 packages are preserved; each version has separate publication and installed-artifact evidence.

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.

Version 1.1.0 includes the passive environment command and MCP tool first reviewed as unreleased source, and adds resumable maintainer release coordination. The archive hash above records historical lineage, not the current release archive. Current source, interface, artifact, publication and presentation checks have their own reports. Earlier native/inference and installed-package results do not validate a new artifact. All current distribution routes use the same engine; older versions remain immutable recovery material.

Version 1.2.0 adds global push-to-talk, explicit focused-field insertion and eight optional offline speaker backends. The exact inventory contains 73 CLI commands, 46 MCP tools and 38 model identities. The 1.2.1 Mac correctness patch requires positive selected-text writability and an empty caret, refuses explicit disabled states, checks the focused application/field and confirms the inserted Unicode span after one selected-text write. Interrupted tap delivery skips insertion while retaining the transcript. Disposable macOS 15 runs on Intel and Apple Silicon verify owned TextEdit Unicode insertion, isolated worker insertion and cleanup, selection and application-change refusal, and F20 listener registration, liveness and cleanup. These checks do not exercise physical keys, microphones, user permission setup, third-party fields or native secure/read-only fields. Current source/example, installed-artifact, model inference, publication and website checks retain separate receipts. A prepared guide or successful build alone does not establish publication.

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.