@aletheia-labs/cli

Operational local CLI for Aletheia workspaces.

This package creates a local .aletheia/ workspace, records append-only observations and candidate memories, drafts governed plans, classifies proposed actions, records human approval packets, runs only approved low-risk local outputs, and serves workspace evidence through the auditor UI. Workspace evidence can also be exported and imported as portable JSON bundles. The package also includes an explicit stdio MCP bridge for local agent/tool integration, a deterministic operational evaluation gate, public host contracts, backup-first migration checks, and read-only doctor diagnostics for local runtime/workspace health.

Running

After installation, use the package binary:

aletheia --help

From this repository checkout, use the local entrypoint:

node packages/cli/bin/aletheia.mjs --help

Commands

aletheia --help

Shows available commands and the operational boundary.

aletheia --help

aletheia --version

Prints the installed CLI package version.

aletheia --version

aletheia doctor

Runs read-only diagnostics for the local runtime, native SQLite in-memory open, package metadata, workspace manifest, generated directories, and JSONL ledgers.

aletheia doctor
aletheia doctor --json

The command does not repair native modules, migrate workspaces, write reports, or grant permission to execute effects.

aletheia init

Creates a local .aletheia/ workspace in the current directory and writes an initial report.

aletheia init

Useful options:

aletheia init --json
aletheia init --force

--force rewrites the manifest and creates another init report. It does not clear the append-only ledgers.

aletheia observe "<text>"

Appends an operator observation as candidate evidence. The command records one event, one observation, and one fresh workspace report.

aletheia observe "The project prefers explicit receipts."

Useful options:

aletheia observe "The project prefers explicit receipts." --json
aletheia observe "Only use approved release commands." --visibility private

Observations are candidate evidence. They are not permission, not trusted memory, and not authorization to act.

aletheia remember "<text|json>"

Records a candidate memory proposal. Text input becomes a local candidate claim; JSON input can come from an observation or another host.

aletheia remember "The project prefers explicit receipts." --type policy
aletheia remember ./observation.json --type policy --json
aletheia remember "Tavian entrega su nombre durante el Cierre Mudo." --type canon_fact --replaces mem:old

The command only writes status: candidate. It does not promote memory to verified or trusted. --replaces records explicit replacement lineage, but it does not deprecate the old memory by itself.

aletheia memory <subcommand>

Lists, reviews, and transitions candidate memory through human decisions.

aletheia memory list --status candidate
aletheia memory review --json
aletheia memory review --with-replacement-signals --json
aletheia memory hygiene --profile novel --json
aletheia memory promote mem:123 --approver Gabriel
aletheia memory reject mem:123
aletheia memory human-required mem:123
aletheia memory reframe mem:123 --claim "Clean canon wording." --promote --deprecate-original
aletheia memory resolve mem:123 --decision "yes" --claim "Clean canon decision." --promote
aletheia memory lineage mem:123 --json
aletheia memory deprecate mem:old --replaced-by mem:new
aletheia memory bulk-promote mem:a mem:b mem:c

Transitions are append-only. promote records verified, not trusted. Use memory reframe for approve-with-edit flows so unresolved questions do not become canon. Use memory resolve for pending editorial decisions; it creates the clean claim and deprecates the original by default. memory lineage is a read-only audit view of reframe, replacement, and deprecation links.

memory hygiene --profile novel is a read-only candidate cleanup pass. It asks "does this help write future chapters?", scores editorial durability, detects raw dialogue/literal excerpts, flags wrong memory types, reports conceptual duplicates against verified canon, and returns explicit recommendations such as reject_raw_quote, reframe_as_magic_rule, duplicate_of_verified, and ambient_detail_do_not_promote.

aletheia agent ingest <suggestions.jsonl>

Ingests structured agent suggestions as observations, candidate memories, editorial style issues, and action queue items. Agent recommendations are priority signals, not authority.

aletheia agent ingest ./suggestions.jsonl --json

Input may be JSONL, a JSON array, or an object with findings. Outputs produced from llmHandoff.agentPackets[] are directly ingest-compatible, but LLM-shaped findings must include authorityBoundary set to agent_output_is_motion_not_authority; otherwise ingest fails closed.

aletheia agent run editorial-board

Runs the governed editorial-board orchestrator for one chapter. It exports current canon, audits the chapter, records candidate suggestions by default, reads memory recommendations, and returns the human action queue. It never promotes, rejects, deprecates, trusts, seals, or resolves memory automatically.

aletheia agent run editorial-board \
  --chapter book/capitulos/capitulo-03.md \
  --profile novel \
  --json

Add --llm-agents when a host such as Codex should also receive governed LLM reviewer packets. Aletheia prepares the packets; the host runs any model:

aletheia agent run editorial-board \
  --chapter book/capitulos/capitulo-03.md \
  --profile novel \
  --llm-agents \
  --json

aletheia agent prepare editorial-board

Prepares host-executed LLM editorial-agent packets without calling a model. Packets include governed context and an output schema for specialized reviewers such as style-agent, continuity-agent, magic-agent, reveal-discipline-agent, and prose-rhythm-agent.

aletheia agent prepare editorial-board \
  --chapter book/capitulos/capitulo-03.md \
  --recent book/capitulos/capitulo-02.md \
  --objective "raise pressure without revealing the seal" \
  --agent style-agent \
  --agent continuity-agent \
  --json

Agent outputs remain motions. Feed returned JSON back through aletheia agent ingest; human review commands still decide canon.

With --json, the command prints llmHandoff and agentPackets directly. Each agent packet contains the subagent prompt, scoped context, output contract, line map, example output, ingest contract, and authority boundary, so a host such as Codex can launch reviewers without opening the generated report first. The handoff also includes an execution plan, token-budget policy, and the exact agent ingest contract for returning findings as auditable motions.

aletheia canon export

Exports verified/trusted memory as a clean canon packet for writing.

aletheia init --profile novel
aletheia canon export --profile novel --for-writing --json

Candidate, rejected, deprecated, sealed, and human-required memories are suppressed and counted in the export.

When an editorial compass charter exists, --for-writing puts creative north, Genre / Tone Charter, do-not-reinforce constraints, and drift warnings before factual canon sections.

Exported canon records also carry usageGuidance so hosts can distinguish "respect this if relevant" from "reuse this again."

Canon export keeps narrative canon separate from process_rules, style_guide, format_conventions, prose_rhythm_rules, and dialogue_clarity_rules. Style-guide records do not enter the narrative memory pool.

aletheia compass <subcommand>

Records and inspects a fiction-direction charter.

aletheia compass charter set \
  --genre "fantasia clasica epica" \
  --creative-north "magia tangible, politica mitica, poca burocracia" \
  --tone "mitico" \
  --do-not-reinforce "actas"
aletheia compass charter show --json
aletheia compass drift book/capitulos --json
aletheia compass variety \
  --recent book/capitulos/capitulo-10.md \
  --recent book/capitulos/capitulo-11.md \
  --recent book/capitulos/capitulo-12.md \
  --window 3 \
  --json

The compass is editorial guidance. It scores candidates and warns about drift, repetition pressure, and overused narrative resources, but it does not promote, reject, deprecate, or trust memory.

aletheia variety accept-repeat

Records that a repeated spell, character, motif, or scene resource is an intentional callback.

aletheia variety accept-repeat "Cierre de Paso" \
  --reason "motivo tematico deliberado" \
  --expires-after 2 \
  --json

The exception only reduces variety-report noise. It does not change canon authority or authorize reuse.

aletheia editorial style-guide <subcommand>

Records manuscript style rules outside narrative memory and audits chapter files against them.

aletheia editorial style-guide set \
  --rule "Cursiva para pensamiento directo o palabra mental" \
  --rule "Negrita solo para texto visible dentro del mundo narrativo" \
  --rule "Evitar rachas de párrafos breves fuera de diálogo" \
  --rule "Rayas para diálogo y murmullos audibles" \
  --json

aletheia editorial style-guide audit book/capitulos/capitulo-02.md --json

Rules are stored in .aletheia/editorial-style-guide.jsonl as editorial_style_rule, format_convention, prose_rhythm_rule, or dialogue_clarity_rule. Audits report actionable issues such as thought_format, world_text_format, paragraph_rhythm, dialogue_dash, and voice_clarity. They are editorial guidance only; they never promote, reject, or compete with canon memories.

aletheia chapter <subcommand>

Builds the pre/post writing loop for fiction chapters.

aletheia chapter brief \
  --next 13 \
  --recent book/capitulos/capitulo-10.md \
  --recent book/capitulos/capitulo-11.md \
  --recent book/capitulos/capitulo-12.md \
  --json

aletheia chapter audit book/capitulos/capitulo-13.md --record-candidates --json
aletheia chapter review book/capitulos/capitulo-13.md --profile novel --full --json

chapter brief separates mandatory canon, available canon, resource exhaustion, open promises, reveal guards, character exposure, magic economy, scene-resolution variety, negative-space suggestions, and active style-guide rules. chapter audit checks the drafted chapter, includes style-guide issues, and can record extracted deltas as candidate memory only. chapter review orchestrates the full post-draft table: canon export, chapter audit, style issues, continuity pressure, memory recommendations, and open human action queue items. --full records extracted deltas as candidates; it still never promotes canon.

aletheia canon pressure

Reports which active canon memories are exerting the strongest influence on recent writing.

aletheia canon pressure --recent book/capitulos/capitulo-12.md --json

Control memories such as style, process, policy, reveal-boundary, and editorial-note records are reported as ignored control memories instead of narrative pressure.

aletheia retcon plan

Drafts human review work for a creative-direction change.

aletheia retcon plan \
  --from-tone "actas, registros, procedimientos" \
  --toward "politica mitica y magia tangible" \
  --json

Retcon plans queue suggested deprecations or reframes. They never change canon by themselves.

aletheia action-queue <subcommand>

Lists or resolves editorial review actions.

aletheia action-queue list --json
aletheia action-queue resolve queue:123 --decision keep_candidate

aletheia report <kind>

Provides editorial report views:

aletheia report full
aletheia report summary
aletheia report action-queue

Full reports include an editorialReview section that the auditor UI renders as a read-only Review tab with copyable CLI decision commands. Reports also include an editorialCompass section that the auditor UI renders as a read-only Compass tab. Reports also include an editorialStyleGuide section that the auditor UI renders as a read-only Style Guide tab with active rules, style issues, audit violations, and suggestions. summary separates current open action-queue counts from historical resolved counts.

aletheia watch <path>

Scans explicit story markers such as CANON:, MYSTERY:, MAGIC:, RUMOR:, and TODO:. It suggests candidates by default and records them only with --record-candidates.

aletheia watch book/capitulos
aletheia watch book/capitulos --record-candidates --json

aletheia inspect

Prints a read-only summary of the local workspace: project id, workspace path, event count, observation count, memory count, plan count, action count, and the latest records.

aletheia inspect
aletheia inspect --json
aletheia inspect --bundle ./.aletheia/exports/workspace-bundle.json --json

aletheia plan "<goal>"

Drafts a deterministic local plan from the workspace evidence. Candidate memory can be cited as context, but it is marked candidate_context_only and cannot authorize effects.

aletheia plan "Prepare release notes from governed evidence"
aletheia plan "Prepare release notes" --limit 5 --json

aletheia propose-action <action.json>

Classifies a proposed action without executing it. Sensitive actions return ask_human. Low-risk local actions still require cited verified or trusted memory before they can be allowed.

aletheia propose-action ./action.json --json
aletheia propose-action ./action.json --memory mem:verified-local-policy

Minimal action JSON:

{
  "classifiedAction": "local_report",
  "target": "release-report.json",
  "params": {
    "report": {
      "status": "ok"
    }
  },
  "citedMemoryIds": ["mem:verified-local-policy"]
}

aletheia run-local <action.json|action-id>

Runs a proposed action only when the action decision is allow_local_shadow. Execution is deliberately narrow: local outputs are written under .aletheia/outputs/, never as arbitrary shell commands.

aletheia run-local ./action.json --json
aletheia run-local act:123 --json

aletheia approve-action <action-id|approval.json>

Records a human approval or denial packet for exactly one action proposal. Approval packets are inspectable evidence. They do not make memory authoritative and do not make the CLI execute sensitive external effects.

aletheia approve-action act:123 --decision approved --approver Gabriel --expires-at 2026-05-19T12:00:00.000Z
aletheia approve-action act:123 --decision denied --reason "Not ready for publication" --json

aletheia check-approval <action-id>

Checks whether an approval packet still matches one action proposal.

aletheia check-approval act:123 --approval appr:456 --json

Possible outcomes include approved, denied, expired, missing, and mismatch.

aletheia export [bundle.json]

Exports the current workspace ledgers as a portable JSON evidence bundle. With no path, the bundle is written under .aletheia/exports/.

aletheia export
aletheia export ./aletheia-workspace-bundle.json --json

aletheia import <bundle.json>

Imports a workspace evidence bundle into the current directory. If the directory does not have an Aletheia workspace yet, the command initializes one first. Existing records are skipped by id, so re-importing the same bundle is append-only and non-duplicating.

aletheia import ./aletheia-workspace-bundle.json --json

aletheia mcp --stdio

Starts the explicit local MCP bridge.

aletheia mcp --stdio

The MCP server exposes aletheia_inspect, aletheia_recall, aletheia_observe, aletheia_plan, aletheia_audit, aletheia_propose_action, aletheia_export, aletheia_memory_review, aletheia_memory_reframe, aletheia_memory_resolve, aletheia_memory_lineage, aletheia_agent_ingest, aletheia_action_queue, aletheia_canon_export, aletheia_compass_charter, aletheia_compass_drift, aletheia_compass_variety, aletheia_variety_accept_repeat, aletheia_style_guide_set, aletheia_style_guide_audit, aletheia_chapter_brief, aletheia_chapter_audit, aletheia_run_chapter_review, aletheia_run_editorial_board, aletheia_prepare_editorial_agents, aletheia_get_style_issues, aletheia_get_memory_recommendations, aletheia_get_action_queue, aletheia_get_chapter_brief, aletheia_canon_pressure, and aletheia_retcon_plan.

It is stdio-only in this phase. It does not execute sensitive effects, approve actions, promote memory, or run as a daemon. Agent ingest records candidates only.

aletheia eval [pack]

Runs deterministic operational evaluations and writes an audit-ready JSON report. The default pack is operational-boundaries.

aletheia eval
aletheia eval --output ./phase16-eval-report.json --json
aletheia eval --fail-on-violation

The pack checks candidate-memory refusal, verified low-risk local output, sensitive-action escalation, stale allow rechecking, and approval packet scoping.

aletheia contracts

Prints the public CLI/workspace contract for host integration.

aletheia contracts --json

The contract describes commands, MCP tools, workspace files, action classes, and boundaries. It is metadata only, not production authorization.

aletheia migrate

Backs up the current workspace and checks whether its format needs migration.

aletheia migrate
aletheia migrate --backup ./workspace-backup.json --json

Version 1 is already current, so the command returns already_current after writing a backup bundle.

aletheia security-review

Prints a deterministic local security review of the CLI/package surface.

aletheia security-review --json

The review marks npm publication as manual because a real publish requires an operator OTP.

aletheia serve [report.json ...]

Starts the read-only auditor UI. With no report paths, it generates and serves a current report from .aletheia/.

aletheia serve
aletheia serve --port 4191
aletheia serve ./evidence/evaluation-suite/phase-6-report.json

Useful options:

aletheia serve --host 127.0.0.1 --port 4191

aletheia audit [report.json ...]

Alias for serve. Use it when the intent is evidence review.

aletheia audit ./evidence/evaluation-suite/phase-6-report.json --port 4192

Workspace Files

The CLI writes local append-only evidence under .aletheia/:

.aletheia/manifest.json
.aletheia/events.jsonl
.aletheia/observations.jsonl
.aletheia/memories.jsonl
.aletheia/plans.jsonl
.aletheia/actions.jsonl
.aletheia/approvals.jsonl
.aletheia/agent-suggestions.jsonl
.aletheia/action-queue.jsonl
.aletheia/editorial-charters.jsonl
.aletheia/outputs/*
.aletheia/exports/*.json
.aletheia/backups/*.json
.aletheia/reports/*.json

Boundary

• No provider credentials.
• No daemon or implicit watcher; watch is an explicit one-shot scanner.
• No sensitive effect execution; approval packets are evidence only.
• No arbitrary shell command execution.
• No production authorization.
• No automatic promotion to trusted memory.
• No semantic retrieval, embeddings, or vector storage.

Observations and candidate memories are evidence. They do not become permission.