Operator reference
CLI flags reference
Identify which parser owns an option, find the command family you need, and preview mutation before changing a project or shared run state.
Command boundary
Choose the layer before the flag
The bootstrap, downloaded installer, and runtime CLI have different parsers. The shell bootstrap forwards unknown arguments, but that does not make every installer flag a bootstrap-native option.
01 / Bootstrap
install.sh
Find Python, authenticate or choose the source-available path, fetch and verify the installer.
02 / Project installer
install-trw.py
Install packages and merge selected client/project surfaces.
03 / Runtime CLI
trw-mcp
Serve MCP plus project, diagnostic, data, and maintenance commands.
Installation
Bootstrap-native options
These options are parsed by the public install.sh bootstrap itself. Other arguments are forwarded to the downloaded Python installer.
--api-key KEYInspect
- Scope
- install.sh
- Purpose
- Supplies a hosted API key without waiting for device authorization
- Default or boundary
- TRW_API_KEY or stored credential
--version VERInspect
- Scope
- install.sh
- Purpose
- Pins the release requested from the hosted installer endpoint
- Default or boundary
- TRW_VERSION or latest
--allow-unauthenticatedInspect
- Scope
- install.sh
- Purpose
- Installs the source-available package path without the hosted bundle
- Default or boundary
- off
--require-checksumInspect
- Scope
- install.sh
- Purpose
- Fails closed when the installer endpoint does not provide a checksum
- Default or boundary
- off
--allow-system-pythonInspect
- Scope
- both layers
- Purpose
- Explicitly permits the PEP 668 --break-system-packages fallback
- Default or boundary
- off; prefer pipx or a virtual environment
--help / -hInspect
- Scope
- install.sh
- Purpose
- Prints bootstrap-native options and forwarding behavior
- Default or boundary
- —
| Flag | Scope | Purpose | Default or boundary |
|---|---|---|---|
--api-key KEY | install.sh | Supplies a hosted API key without waiting for device authorization | TRW_API_KEY or stored credential |
--version VER | install.sh | Pins the release requested from the hosted installer endpoint | TRW_VERSION or latest |
--allow-unauthenticated | install.sh | Installs the source-available package path without the hosted bundle | off |
--require-checksum | install.sh | Fails closed when the installer endpoint does not provide a checksum | off |
--allow-system-python | both layers | Explicitly permits the PEP 668 --break-system-packages fallback | off; prefer pipx or a virtual environment |
--help / -h | install.sh | Prints bootstrap-native options and forwarding behavior | — |
Downloaded installer options
Run the downloaded installer with --help to confirm the release you actually received. The current source groups its options as follows.
target_dirInspect
- Scope
- project
- Purpose
- Selects the repository to initialize
- Default or boundary
- current directory
--scriptInspect
- Scope
- interaction
- Purpose
- Runs non-interactively; prompts use defaults and supplied values
- Default or boundary
- off
--name VALUEInspect
- Scope
- project
- Purpose
- Sets the installation ID written to project configuration
- Default or boundary
- derived
--ide LISTInspect
- Scope
- client surfaces
- Purpose
- Selects comma-separated client targets such as cursor-ide,codex
- Default or boundary
- prompted when interactive
--upgradeInspect
- Scope
- packages
- Purpose
- Upgrades the package without rerunning project bootstrap
- Default or boundary
- off
--ai / --no-aiInspect
- Scope
- packages
- Purpose
- Selects the optional AI/LLM extras
- Default or boundary
- prompt/profile dependent
--sqlite-vec / --no-sqlite-vecInspect
- Scope
- packages
- Purpose
- Selects the optional sqlite-vec integration
- Default or boundary
- prompt/profile dependent
--offlineInspect
- Scope
- packages
- Purpose
- Uses embedded wheels only; transitive dependencies must already be available
- Default or boundary
- off
--pip-target DIRInspect
- Scope
- packages
- Purpose
- Installs packages into a specific import directory
- Default or boundary
- site packages
--telemetry / --no-telemetryInspect
- Scope
- hosted connection
- Purpose
- Records explicit telemetry consent
- Default or boundary
- not inferred from an API key
--skip-authInspect
- Scope
- hosted connection
- Purpose
- Skips device authorization when credentials or non-hosted setup make it unnecessary
- Default or boundary
- off; implicit in script mode
--user-tier / --no-user-tierInspect
- Scope
- memory
- Purpose
- Explicitly provisions or denies the machine-local user memory tier
- Default or boundary
- project-only
--with-proprietaryInspect
- Scope
- licensed packages
- Purpose
- Adds licensed TRW packages when entitlement is available
- Default or boundary
- off
--license-key KEYInspect
- Scope
- licensed packages
- Purpose
- Overrides automatic entitlement derivation
- Default or boundary
- TRW_LICENSE_KEY or derived entitlement
--proprietary-version PKG==VERInspect
- Scope
- licensed packages
- Purpose
- Pins one licensed package; repeat for multiple packages
- Default or boundary
- release-selected versions
--backend-url URLInspect
- Scope
- testing
- Purpose
- Overrides the entitlement endpoint for controlled testing
- Default or boundary
- api.trwframework.com
| Flag | Scope | Purpose | Default or boundary |
|---|---|---|---|
target_dir | project | Selects the repository to initialize | current directory |
--script | interaction | Runs non-interactively; prompts use defaults and supplied values | off |
--name VALUE | project | Sets the installation ID written to project configuration | derived |
--ide LIST | client surfaces | Selects comma-separated client targets such as cursor-ide,codex | prompted when interactive |
--upgrade | packages | Upgrades the package without rerunning project bootstrap | off |
--ai / --no-ai | packages | Selects the optional AI/LLM extras | prompt/profile dependent |
--sqlite-vec / --no-sqlite-vec | packages | Selects the optional sqlite-vec integration | prompt/profile dependent |
--offline | packages | Uses embedded wheels only; transitive dependencies must already be available | off |
--pip-target DIR | packages | Installs packages into a specific import directory | site packages |
--telemetry / --no-telemetry | hosted connection | Records explicit telemetry consent | not inferred from an API key |
--skip-auth | hosted connection | Skips device authorization when credentials or non-hosted setup make it unnecessary | off; implicit in script mode |
--user-tier / --no-user-tier | memory | Explicitly provisions or denies the machine-local user memory tier | project-only |
--with-proprietary | licensed packages | Adds licensed TRW packages when entitlement is available | off |
--license-key KEY | licensed packages | Overrides automatic entitlement derivation | TRW_LICENSE_KEY or derived entitlement |
--proprietary-version PKG==VER | licensed packages | Pins one licensed package; repeat for multiple packages | release-selected versions |
--backend-url URL | testing | Overrides the entitlement endpoint for controlled testing | api.trwframework.com |
Runtime CLI
Global trw-mcp options
Place global options before the subcommand. With no subcommand, trw-mcp starts the stdio server. Use trw-mcp --help as the authoritative view for the installed version.
--version / -VInspect
- Scope
- process
- Purpose
- Prints the version and exits
- Default
- —
--debugInspect
- Scope
- logging
- Purpose
- Enables debug logging to stderr and .trw/logs
- Default
- off
--verbose / -vInspect
- Scope
- logging
- Purpose
- Raises verbosity; repeat for debug plus a log file
- Default
- 0
--quiet / -qInspect
- Scope
- logging
- Purpose
- Suppresses output below warning
- Default
- off
--log-level LEVELInspect
- Scope
- logging
- Purpose
- Sets an explicit level and overrides verbosity/debug selection
- Default
- automatic
--log-jsonInspect
- Scope
- logging
- Purpose
- Forces structured JSON output instead of TTY detection
- Default
- automatic
--allow-unsignedInspect
- Scope
- MCP security
- Purpose
- Allows peers absent from the signed registry and emits audit events
- Default
- off
--memory-db PATHInspect
- Scope
- recall
- Purpose
- Adds a repeatable external read-only memory database to recall
- Default
- none
| Flag | Scope | Purpose | Default |
|---|---|---|---|
--version / -V | process | Prints the version and exits | — |
--debug | logging | Enables debug logging to stderr and .trw/logs | off |
--verbose / -v | logging | Raises verbosity; repeat for debug plus a log file | 0 |
--quiet / -q | logging | Suppresses output below warning | off |
--log-level LEVEL | logging | Sets an explicit level and overrides verbosity/debug selection | automatic |
--log-json | logging | Forces structured JSON output instead of TTY detection | automatic |
--allow-unsigned | MCP security | Allows peers absent from the signed registry and emits audit events | off |
--memory-db PATH | recall | Adds a repeatable external read-only memory database to recall | none |
Command map
25 commands, grouped by intent
This map is faster to scan than a mixed flag dump. Ask a command for its own help before mutation: trw-mcp <command> --help.
Serve
serveRun the stdio MCP server; also the no-subcommand default
Project setup
init-projectupdate-projectuninstallCreate, refresh, or remove project-managed surfaces
Inspect
auditdoctorconfig-referencecheck-instructionstendenciesversion-statusRead configuration, installation health, instruction integrity, and version drift
Data movement
exportimport-learningssession-changelogMove explicit records or render a run changelog
Local ceremony
localgcUse fallback ceremony operations or inspect and sweep stale run state
Coordination
dispatchRun a supported coding-agent CLI for a bounded second opinion
Channels and access
authchannel-doctortierManage hosted authentication, channel hygiene, and entitlements
Memory maintenance
learn-drainmaintain-verifyFlush pending write-ahead learn records on demand, and re-verify stored learnings that carry assertions
Requirements
prd-stateMove a PRD through the WIP-limited scheduling ledger's execution states
Release engineering
build-releaseprepare-candidatecommit-candidateBuild a bundled-data release artifact, or publish an isolated candidate commit without touching shared checkout state
Mutation safety
Preview the exact scope
These commands do not carry the same risk. Review what each one changes rather than applying a blanket “commit and restore” recovery recipe in a shared worktree.
01 / --dry-run
update-project
Merges framework-managed project and client surfaces
Review the preview and concurrent worktree ownership before running without dry-run.
02 / --dry-run
uninstall
Removes managed TRW surfaces; --user-tier broadens scope
Use --keep-memory when the learning corpus must survive. Do not combine --yes with an unreviewed scope.
03 / default / --dry-run
gc
--no-dry-run marks stale active runs abandoned
It changes run state, not source files. Confirm staleness and session ownership first.
Diagnostics
Increase signal deliberately
Start with doctor for read-only installation diagnostics. Add logging only when you need a trace, and keep global logging options before the command.
trw-mcp doctorRead-only checks for environment, config, MCP registration, profiles, instructions, and memory.
trw-mcp --debug serveDebug output to stderr and the project log surface.
trw-mcp -vv auditRepeated verbosity enables debug-level detail plus a log file.