CLI flags reference
Every installer flag, every trw-mcp subcommand flag, and the env vars that flip debug/verbose behavior. Reference tables only.
Installer flags
Flags accepted by install.sh (which shells out to install-trw.py). The installer is the canonical entry point — run curl -fsSL https://trwframework.com/install.sh | bash for user projects.
| Flag | Short | What it does | Example |
|---|---|---|---|
| target_dir | — | Positional. Project directory to install into. Defaults to the current directory. | python3 install-trw.py . |
| --upgrade | — | Upgrade the trw-mcp package without re-running project bootstrap. | --upgrade |
| --ai / --no-ai | — | Install (or skip) the [ai] extra (Anthropic SDK for experimental AI-assisted tooling). | --no-ai |
| --sqlite-vec / --no-sqlite-vec | — | Install (or skip) the [vectors] extra that enables sqlite-vec embeddings. | --sqlite-vec |
| --quiet | -q | Minimal output; one line per phase. | --quiet |
| --script | — | Force non-interactive mode. All prompts use their defaults; required values must come from flags or env. | --script |
| --name VALUE | — | Installation ID written to .trw/config.yaml. | --name my-repo |
| --api-key VALUE | — | Platform API key for hosted sync and telemetry. | --api-key trw_dk_... |
| --telemetry / --no-telemetry | — | Opt in or out of platform telemetry. Default in script mode: --no-telemetry. | --telemetry |
| --skip-auth | — | Skip the device-authorization flow during install. | --skip-auth |
| --pip-target DIR | — | Install packages to DIR instead of the default site-packages (useful for tmpfs or container overlays). | --pip-target /tmp/pkgs |
| --ide VALUE | — | Client profile(s) to configure. Comma-separated. Prompted in interactive mode. | --ide cursor-ide,codex,gemini |
trw-mcp flags
trw-mcp is both an MCP server (default behavior: run the server) and a small CLI for bootstrap, maintenance, and offline fallback. Global flags apply to every subcommand.
Global flags
| Flag | Short | What it does | Default |
|---|---|---|---|
| --version | -V | Print version and exit. | — |
| --debug | — | Enable debug logging to .trw/logs/ and stderr. | off |
| --verbose | -v | Increase verbosity (-v DEBUG, -vv DEBUG+file). Stacks with --debug. | 0 |
| --quiet | -q | Suppress everything below WARNING. | off |
| --log-level LEVEL | — | Explicit level: DEBUG, INFO, WARNING, ERROR, CRITICAL. Overrides -v/--debug. | auto |
| --log-json | — | Force JSON log output (default: auto-detect TTY). | auto |
| --transport VALUE | — | Transport: stdio, sse, streamable-http. | stdio |
| --host VALUE | — | Bind address for HTTP transport. | 127.0.0.1 |
| --port VALUE | — | Bind port for HTTP transport. | 8100 |
Subcommands
Invoked as trw-mcp <subcommand> [flags]. Omitted or serve runs the MCP server.
| Subcommand | Purpose | Notable flags |
|---|---|---|
| serve | Run the MCP server. Default when no subcommand is supplied. | (uses global --transport, --host, --port) |
| init-project | Bootstrap TRW in a project directory. | --force, --ide, --source-package, --test-path, --runs-root |
| update-project | Update framework files without clobbering user config. | --pip-install, --dry-run, --ide |
| audit | Comprehensive TRW health audit for a project. | --format, --output, --fix |
| export | Export learnings, runs, or analytics to JSON/CSV. | --scope, --format, --output, --since, --min-impact |
| import-learnings | Import learnings from an export file. | --min-impact, --tags, --dry-run |
| auth | Manage platform authentication: login, logout, status. | --api-url (on login) |
| uninstall | Remove TRW files from a project. | --dry-run, --yes |
| config-reference | Print every TRW_* env var with its default and description. | — |
| check-instructions | Validate instruction files reference only exposed MCP tools. | — |
| local | Offline fallback: init a run, write a checkpoint without the MCP server. | --task, --message, --run-path |
| gc | Sweep stale active runs. Default is dry-run (reports only). | --no-dry-run, --staleness-hours, --grace-hours, --json |
| build-release | Build a release bundle of bundled data. | --version, --output-dir, --push, --backend-url, --api-key |
Skill invocation
TRW ships slash-command skills (for example /trw-ceremony-guide, /trw-prd-ready) that each client invokes in its native slash surface — Claude Code and Cursor IDE type them into the chat, opencode and Codex execute them through their command menus. The installer writes the skill files to each client's skill directory so invocation is uniform across clients; the underlying CLI is the same either way.
Debugging flags
Preferred path: trw-mcp --debug (writes to .trw/logs/ and stderr) or -vv (DEBUG plus a log file).
| Setting | What it does | Example |
|---|---|---|
| --debug | Enable debug logs + write to .trw/logs/. | trw-mcp --debug serve |
| -vv | DEBUG level plus per-session log file. | trw-mcp -vv |
| --log-json | Force JSON output for log aggregation. | trw-mcp --log-json |
| TRW_DEBUG | Env-var equivalent of config.debug. Same effect as --debug. | TRW_DEBUG=1 trw-mcp |
Crash traces land in .trw/logs/crash.log — see server/__main__.py for the top-level crash handler.
Related pages