Every Ought workflow is driven through the ought CLI. Run ought help or ought <command> --help for the full flag listing.
Global flags
These work on every subcommand:
--config <path>— use a specificought.tomlinstead of the one discovered from the working directory.--quiet— suppress all output except errors and the final summary.--json— emit structured JSON instead of human-readable text.--junit <path>— write JUnit XML results to the given file.--color <auto|always|never>— control terminal color.--verbose— enable debug-level output.
ought init
Scaffold ought.toml and an example spec in the current directory.
ought initought generate
Read your specs and source code and write test files. Tests are annotated with the clause they enforce, so failures map back to specific lines in the spec.
ought generate # regenerate stale clauses across all specs
ought generate specs/auth.ought.md # limit to one spec (positional path or glob)
ought generate --force # regenerate every clause regardless of hash
ought generate --check # exit 1 if any generated tests are stale (for CI)ought run
Execute the generated tests and produce a clause-mapped report.
ought run # run everything
ought run specs/auth.ought.md # run tests from matching specs
ought run --fail-on-should # exit 1 on SHOULD failures too (default: MUST only)ought check
Validate spec file syntax without generating or running tests.
ought checkought inspect
Show the generated test code for a specific clause.
ought inspect auth::login::must_return_jwtought diff
Show the diff between the current generated tests and what would be produced by a fresh generate.
ought diffought extract
Reverse-engineer .ought.md spec drafts from your existing source. Audits whatever specs you already have (rule-based, no LLM), then dispatches LLM agents to draft new specs for uncovered source areas.
ought extract # extract from configured [context].search_paths
ought extract src/auth/ src/billing/ # limit to specific source paths
ought extract --dry-run # print drafts to stdout instead of writing files
ought extract --out specs/drafts/ # write drafts somewhere other than the first [specs].roots entry
ought extract --force # overwrite existing .ought.md files
ought extract --no-audit # skip the audit phase over existing specs
ought extract --model claude-opus-4-7 # override the configured generator model
ought extract --parallelism 4 # cap concurrent agentsought watch
Watch for file changes and re-run affected specs.
ought watchought view
Launch the visual spec viewer in the browser.
ought view # serves on :3333, opens the browser
ought view --port 8080
ought view --no-openought analyze
Spec-level analysis commands.
ought analyze survey
Find behaviors in your source code that are not covered by any spec clause.
ought analyze survey
ought analyze survey src/auth/ought debug
Investigate failing clauses with git history.
ought debug blame
Explain why a clause is failing by correlating with recent commits.
ought debug blame auth::login::must_return_jwtought debug bisect
Binary-search git history to find the commit that broke a clause.
ought debug bisect auth::login::must_return_jwt
ought debug bisect auth::login::must_return_jwt --range abc123..def456
ought debug bisect auth::login::must_return_jwt --regenerate--regenerate regenerates tests at each commit instead of reusing the current manifest — slower but accurate when the spec itself has changed across the range.
ought mcp
Model Context Protocol server commands.
ought mcp serve
Start the MCP server.
ought mcp serve # stdio transport (for local IDE integration)
ought mcp serve --transport sse --port 8765 # SSE transport for remote clientsought mcp install
Register ought with MCP-compatible coding agents.
ought mcp install