Skip to content
Reasons Forge

CLI Reference

Global options

Section titled “Global options”
reasonsforge [OPTIONS] COMMAND [ARGS]
Option Description
--version Show version and exit
--help Show help and exit

Forge commands

Section titled “Forge commands”

Each forge type can be run as a top-level command for the full pipeline, or with subcommands for individual steps.

reasonsforge code

Section titled “reasonsforge code”

Build a knowledge base from a codebase.

Terminal window
# Full pipeline
reasonsforge code --repo ./my-project


# Individual steps
reasonsforge code scan --repo ./my-project
reasonsforge code explore --repo ./my-project --loop 50
reasonsforge code propose-beliefs --auto
reasonsforge code derive --exhaust --auto
reasonsforge code status
Option Description
--repo Path to the git repository (default: .)
--domain Domain description
--since Analyze commits since this date or SHA
--limit Max files to explore (default: 500)

Subcommands: scan, explore, explain, walk-commits, propose-beliefs, accept-beliefs, review-proposals, verify, derive, topics, status, update

reasonsforge product

Section titled “reasonsforge product”

Build a knowledge base from product data in issue trackers.

Terminal window
# Full pipeline
reasonsforge product --github owner/repo


# Individual steps
reasonsforge product init --github owner/repo
reasonsforge product scan
reasonsforge product ingest docs/ --glob-pattern "**/*.md"
reasonsforge product explore --loop 20
reasonsforge product derive --exhaust --auto
Option Description
--github GitHub repository (owner/repo format)
--gitlab GitLab project path
--jira Jira project key
--jira-url Jira base URL
--domain Domain description for product context

Subcommands: init, scan, ingest, explore, propose-beliefs, accept-beliefs, review-proposals, derive, generate-summary, summary, topics, status, update

reasonsforge project

Section titled “reasonsforge project”

Build a knowledge base from project management data.

Terminal window
# Full pipeline
reasonsforge project --github owner/repo


# Individual steps
reasonsforge project init --github owner/repo
reasonsforge project scan
reasonsforge project explore --loop 20
reasonsforge project research --high-impact
reasonsforge project sprint-plan
Option Description
--github GitHub repository (owner/repo format)
--gitlab GitLab project path
--jira Jira project key
--jira-url Jira base URL
--domain Domain description

Subcommands: init, scan, explore, propose-beliefs, accept-beliefs, review-proposals, research, derive, review-beliefs, repair, summary, sprint-plan, topics, status, update

reasonsforge meta

Section titled “reasonsforge meta”

Cross-domain reasoning across expert belief networks. Aggregates beliefs from other forges and finds emergent insights invisible to any single expert.

Terminal window
# Initialize with expert repos
reasonsforge meta init code=/path/to/code-expert project=/path/to/project-expert


# Import beliefs from experts, derive, detect contradictions, summarize
reasonsforge meta update


# Individual steps
reasonsforge meta import
reasonsforge meta derive --auto
reasonsforge meta contradictions --auto
reasonsforge meta summary


# Ask questions across all domains
reasonsforge meta ask "What are the top risks?"
Option Description
experts Expert repos as NAME=PATH pairs (init only)
--domain Domain description
--budget Max beliefs per agent for derive (default: 300)
--skip Steps to skip in update (import, derive, contradictions, summary)

Subcommands: init, import, derive, ask, contradictions, summary, topics, status, update

reasonsforge document

Section titled “reasonsforge document”

Build a knowledge base from documents and PDFs with section-based chunking.

Terminal window
reasonsforge document --sources-dir ./docs
reasonsforge document --pdf paper.pdf
Option Description
--sources-dir Path to documents directory (default: sources)
--pdf PDF files to ingest (repeatable)
--domain Domain description for derive context
--recursive, -r Recurse into subdirectories

Common options

Section titled “Common options”

These options are shared across forge types:

Option Description
--model LLM model to use (default: claude)
--timeout LLM timeout in seconds (default: 600)
--output Output database path (default: reasons.db)
--rounds Convergence loop cycles (default: 3)
--max-derive-rounds Max derive rounds per cycle (default: 10)
--parallel Parallel LLM calls (default: 1)

Sandbox commands

Section titled “Sandbox commands”

reasonsforge run

Section titled “reasonsforge run”

Run a forge command inside a sandbox.

Terminal window
reasonsforge run --sandbox=container code --repo ./project
Option Description
--sandbox Sandbox tier: container, vm, lightweight

All arguments after the sandbox flag are passed to the forge command.

Pipeline steps

Section titled “Pipeline steps”

Individual pipeline steps are available under reasonsforge forge:

Terminal window
reasonsforge forge init my-project --domain "My domain"
reasonsforge forge chunk-pdf paper.pdf
reasonsforge forge chunk-docs --input-dir sources
reasonsforge forge summarize --input-dir sources
reasonsforge forge propose-beliefs
reasonsforge forge accept-beliefs
reasonsforge forge pipeline --pdf paper.pdf
reasonsforge forge derive-review-repair
reasonsforge forge index-sources
reasonsforge forge status