CLI reference


configorama [options] <file> [path]
configorama inspect <file> [--view requirements|audit|graph]
configorama capabilities

Command	Purpose
`configorama <file>`	Resolve a config file and print JSON by default.
`configorama inspect <file>`	Introspect a config without resolving it. Returns the full model (`requirements`, `graph`, `audit`) or a single `--view`.
`configorama capabilities`	Print the machine-readable CLI contract (commands, views, formats, error codes, exit codes, flags).
`configorama setup <file>`	Run the interactive setup wizard (experimental).

inspect --view requirements, --view audit, and --view graph cover the three projections. The standalone requirements, audit, and graph commands still work as back-compat aliases but are not part of the documented surface; capabilities lists them under aliases.

Without --view, inspect returns all three projections in one object:


{
  "schemaVersion": 1,
  "config": "config.yml",
  "requirements": {},
  "graph": {},
  "audit": {}
}

Flag	Type	Purpose
`--view`	`requirements`, `audit`, `graph`	Select one `inspect` projection. Omit for the full model.
`--format`	resolve: `json`, `yaml`, `js`, `esm`; graph: `json`, `mermaid`, `dot`	Output format.
`--output`	path	Write output to a file.
`--raw`	boolean	Print scalar path extraction without JSON quoting.
`--copy`	boolean	Copy output to the clipboard.
`--safe`	boolean	Block executable/mutating references during resolution.
`--unsafe`	boolean	Disable the default safe inspection used by `inspect`.
`--safe-root`	path	Restrict file/text references to an allowed root.
`--error-format`	`json`, `human`	Error format on stderr. JSON is the default for `inspect` and `capabilities`; `human` (boxed) is the default for resolve.
`--param`	`key=value`	Pass parameter values (repeatable).
`--allow-unknown`	boolean	Allow unknown variables to pass through.
`--allow-undefined`	boolean	Allow undefined values in the final output.

The CLI uses Configorama’s configured variable syntax. If ${...} belongs to another platform in your project, set a custom syntax in the API layer and read bring your own syntax for wrapper examples.

Path extraction can appear after the file path or before it, depending on the command shape the user prefers:


configorama config.yml .service
configorama .database.name config.yml
configorama config.yml ".servers[0].name"
configorama config.yml ".servers[-1].name"
configorama config.yml '.["special-keys"]["key-with-dash"]'
configorama config.yml .service --raw

Use --copy or -c when a local workflow needs the resolved output on the clipboard. Tests use CONFIGORAMA_CLIPBOARD_COMMAND as a hook, but normal users should rely on the default platform command.

Intent recovery

The CLI corrects legible-but-wrong invocations instead of failing silently:

A mistyped command suggests the closest one (configorama inspekt config.yml → Unknown command "inspekt". Did you mean "inspect"?) rather than treating it as a missing file.
A misspelled flag warns on stderr with the correction (--fromat → Did you mean "--format"?) and keeps running. Arbitrary ${opt:...} passthrough flags such as --stage are never hijacked.
An unknown --view is rejected with the valid views listed.

Capabilities

configorama capabilities prints a machine-readable contract so an agent can read the surface from the tool instead of scraping docs:


configorama capabilities | jq '.commands, .errorCodes, .formats'

It returns name, version, schemaVersion, commands, views, formats, errorCodes, exitCodes, and flags. Exit codes are 0 for success and 1 for any error, with the specific category in the JSON error.code field.

See structured error codes and safe inspection.