CLI Commands

Summary

ToneForge exposes 6 user-facing CLI commands (analyze, show, inject, preview, diff, login) plus a server-only admin tool (toneforge-admin). The CLI surface is implemented in toneforge/cli.py (279 LOC) and toneforge/admin.py (140 LOC). All commands are designed around the .toneprofile as the central artifact — analyze produces it, show/diff inspect it, inject/preview consume it.

analyze accepts four source types: directories, individual files, Claude Code JSONL session history (--source claude, reads from ~/.claude/projects/*/), and stdin. Smart cleaning strips code fences, log lines, URLs, JSON blocks, and import statements before analysis, with a 10MB accumulation cap. Local analysis uses spaCy; --api routes to the hosted service at api.toneforge.io. inject supports 7 targets (claude, cursor, codex, copilot, windsurf, skill, all) with an optional -d flag for a custom project root. The --contexts flag on inject skill (and preview) produces 5 context-specific skill files instead of one generic file.

The admin CLI (toneforge-admin) runs server-side only and requires PostgreSQL access. It covers the full API key lifecycle: create, revoke, usage lookup, and list. It is intentionally not part of the installable CLI package — only available on the server.

Timeline

• 2026-04-11: Context modes design finalized. --contexts flag added to inject and preview. No new top-level commands added — the flag extends existing commands.

Current State

Six commands are implemented. inject covers all 7 targets including the --contexts variant that generates 5 independent context-aware skill files. Admin CLI is separate from the user-facing package. Source readers handle Claude JSONL, text files (.md .txt .rst .adoc), and stdin. The diff command exists for comparing profile versions — useful when reanalyzing after adding new writing samples.

Key Decisions

• 2026-04-11: --contexts as a flag on inject skill rather than a new command — keeps the command surface small. Context mode injection is a variant of skill injection, not a fundamentally different operation.
• 2026-04-11: preview as a distinct command from inject — dry-run is important for first-time users who want to see what will be written before committing to file changes in their project.
• 2026-04-11: toneforge-admin as a separate binary from toneforge — prevents accidental exposure of key management operations in the installed CLI package. Requires intentional server-side setup.

Gotchas & Known Issues

• --source claude reads JSONL from ~/.claude/projects/*/ — path is hardcoded to the default Claude Code location. Non-default Claude installations will not be found automatically.
• Smart cleaning strips code fences and import statements, which means samples that are primarily code will be significantly reduced. Analyze against prose-heavy sources for best results.
• inject all writes to all 7 targets relative to the project root (or -d path). Running it from the wrong directory will scatter config files in the wrong locations.

Open Questions

• Does diff produce a structured delta (machine-readable) or a human-readable summary? The current design doc does not specify output format.
• Is there a --dry-run alias for preview, or are they fully separate commands?

Sources

• 2026-04-11-context-modes-design.md