🠛
OpenForge EDA ›
CLI Reference
CLI Reference
OF-CLI-001
v0.4.0
Complete reference for the openforge command-line tool. The CLI wraps the OpenForge REST API for terminal-based workflows and supports both local execution (running tools directly on the host) and remote execution (submitting jobs to an OpenForge server).
Overview #
$ openforge <command> [subcommand] [options]
Commands:
init Initialize a new OpenForge project
verify Run verification pipelines
analyze Run analysis (timing, power, area)
report Generate consolidated reports
project Manage projects (register, list, sync)
ci CI/CD integration helpers
doctor Check tool installation and health
config View/edit OpenForge configurationGlobal Options #
Option Description Default
--project-dir <path>Path to project root (containing openforge.yaml) Current directory --config <path>Path to openforge.yaml (overrides project-dir search) Auto-detected --server <url>OpenForge server URL for remote execution OPENFORGE_SERVER env var--remoteExecute on remote server instead of locally false--verbose, -vVerbose output (repeat for more: -vv, -vvv) Normal --quiet, -qSuppress non-error output false--jsonOutput results as JSON (for scripting) false--no-colorDisable colored output Auto-detect terminal --help, -hShow help for any command — --versionShow OpenForge version —
openforge init # Initialize a new OpenForge project with directory structure and configuration.
$ openforge init <project-name> [options]
Option Description Default
--template <name>Project template: crypto-accelerator, rng-module, hsm-controller, generic generic--top-module <name>Top-level module name Derived from project name --pdk <name>Target PDK: sky130, gf22fdx sky130--no-examplesDon't generate example design files false--git-initInitialize git repository true
Examples
# Crypto accelerator with SKY130 target
$ openforge init my-ntt --template crypto-accelerator --pdk sky130
# HSM controller for GF22FDX production
$ openforge init hsm-ctrl --template hsm-controller --pdk gf22fdx --top-module hsm_top
# Blank project, no examples
$ openforge init scratch --template generic --no-examplesopenforge verify # Run verification pipelines. This is the primary command for validating designs.
$ openforge verify [options]Pipeline Selection
Option Description
--allRun all verification stages (lint + sim + formal + crypto + analysis) --simRun simulation pipeline only (Verilator + Cocotb) --formalRun formal verification only (SymbiYosys) --cryptoRun all crypto security checks --lintRun linting only (Verible) --stage <name>Run a specific named stage from custom flow definition
Simulation Options
Option Description Default
--coverageEnable line, toggle, and FSM coverage tracking false--traceGenerate waveform trace (VCD/FST) false--trace-format <fmt>Trace format: vcd, fst fst--power-traceCollect Hamming-model power traces false--seed <n>Random seed for reproducible simulation Random --timeout <s>Simulation timeout in seconds 3600--testbench <path>Run specific testbench file only All configured testbenches
Formal Options
Option Description Default
--timeout <s>Formal engine timeout per property 3600--depth <n>BMC exploration depth 50--engine <name>Force specific engine: smtbmc, bmc3, pdr, prove Auto (from config) --property <name>Verify specific property only All properties
Crypto Verification Options
Option Description Default
--constant-timeRun constant-time analysis only — --side-channelRun side-channel simulation only — --traces <n>Number of power traces for SCA 10000--entropyRun entropy flow analysis only — --fipsRun FIPS compliance checks only — --nttRun NTT validation only — --exhaustiveEnable exhaustive mode for NTT validation false
Examples
# Full verification suite
$ openforge verify --all
# Simulation with coverage and power traces
$ openforge verify --sim --coverage --power-trace
# Formal verification with extended depth
$ openforge verify --formal --depth 100 --timeout 7200
# Crypto: constant-time + SCA with 50K traces
$ openforge verify --crypto --constant-time --side-channel --traces 50000
# FIPS compliance check only
$ openforge verify --crypto --fips
# NTT validation in exhaustive mode
$ openforge verify --crypto --ntt --exhaustive
# Run on remote server
$ openforge verify --all --remote --server https://openforge.dyber.orgopenforge analyze # Run physical implementation analysis — timing, power, and area estimation.
$ openforge analyze [options]
Option Description Default
--timingRun static timing analysis (OpenSTA) — --powerRun power estimation — --areaRun area estimation (Yosys synthesis) — --allRun all analysis passes — --vectors <path>Switching activity file (SAIF) for power estimation Auto-generated from sim --pdk <name>Target PDK (overrides config) From openforge.yaml --clock-period <ns>Target clock period for timing From SDC constraints --fips-complianceRun FIPS compliance analysis —
Examples
# Full analysis suite
$ openforge analyze --all
# Timing analysis targeting 200MHz
$ openforge analyze --timing --clock-period 5.0
# Power estimation with custom activity file
$ openforge analyze --power --vectors sim/activity.saif
# FIPS compliance analysis
$ openforge analyze --fips-complianceopenforge report # Generate consolidated reports from verification and analysis results.
$ openforge report [options]
Option Description Default
--format <fmt>Output format: html, json, junit, sarif, csv html--output <path>Output file or directory path reports/--template <path>Custom Jinja2 HTML template Built-in template --include <domains>Include specific domains: sim, formal, crypto, timing All available --openOpen HTML report in default browser false
Examples
# HTML dashboard with all results
$ openforge report --format html --output reports/dashboard.html --open
# SARIF output for GitHub Security tab
$ openforge report --format sarif --output reports/security.sarif
# JUnit XML for CI systems
$ openforge report --format junit --output reports/junit.xml
# JSON for custom processing
$ openforge report --format json --include crypto,formalopenforge project # Manage projects on a remote OpenForge server.
$ openforge project <subcommand> [options]
Subcommand Description
registerRegister current project with OpenForge server listList all projects on the server syncSync local project files to server statusShow project verification status deleteRemove project from server
Examples
# Register with server
$ openforge project register --server https://openforge.dyber.org
# List all projects
$ openforge project list --server https://openforge.dyber.org
# Check status
$ openforge project statusopenforge ci # CI/CD integration helpers for setting up automated verification pipelines.
$ openforge ci <subcommand> [options]
Subcommand Description
setup --githubGenerate .github/workflows/openforge.yml setup --gitlabGenerate .gitlab-ci.yml setup --jenkinsGenerate Jenkinsfile run --stage <name>Run a CI stage (for use inside CI pipelines) statusShow latest CI run status
openforge doctor # Diagnostic tool that checks your OpenForge installation health.
$ openforge doctor
┌─────────────────────────────────────────────────â”
│ OpenForge EDA — System Diagnostics │
└─────────────────────────────────────────────────┘
✓ openforge CLI v0.4.0
✓ Docker v24.0.7
✓ Python v3.11.6
✓ Verilator v5.028 (power-trace: enabled, taint-track: enabled)
✓ Yosys v0.42
✓ SymbiYosys v0.42
✓ Z3 v4.13.0
✓ Bitwuzla v0.4.0
✓ ABC latest
✓ Cocotb v1.9.1
✓ Verible v0.0-3644
✓ OpenSTA v2.6.0
✓ openforge-ct v0.4.0
✓ openforge-sca v0.4.0
✓ openforge-entropy v0.4.0
✓ openforge-fips v0.4.0
✓ openforge-ntt v0.4.0
✓ PDK: SkyWater SKY130 installed
âš PDK: GlobalFoundries 22FDX not installed (optional)
â”â”â” All checks passed (17/17 required, 1 optional missing) â”â”â” openforge config # View and manage OpenForge configuration.
Subcommand Description
showDisplay resolved openforge.yaml configuration validateValidate openforge.yaml against schema set <key> <value>Set a configuration value get <key>Get a configuration value
Environment Variables #
Variable Description Default
OPENFORGE_SERVERDefault OpenForge server URL None (local execution) OPENFORGE_TOKENAuthentication token for remote server None OPENFORGE_PROJECT_DIRDefault project directory Current directory OPENFORGE_CACHE_DIRCache directory for incremental builds ~/.openforge/cacheOPENFORGE_LOG_LEVELLog level: DEBUG, INFO, WARNING, ERROR INFOPDK_ROOTRoot directory for installed PDKs /opt/pdkVERILATOR_ROOTVerilator installation path (if not in PATH) Auto-detect
Exit Codes #
Code Meaning
0All verification and analysis passed 1One or more verification checks failed 2Configuration error (invalid openforge.yaml) 3Tool not found or version mismatch 4Network/server error (remote execution) 5Timeout exceeded 126Permission denied 130Interrupted by user (Ctrl+C)