CLI reference
This page is generated from tungsten --help, command by command. Run tungsten <command> --help for the same text in your terminal.
tungsten
Agent-native SDK generator and MCP/WebMCP compiler
Usage: tungsten [OPTIONS] <COMMAND>
Commands:
check Validate the manifest and specs and report diagnostics
ir Intermediate representation commands
explain Explain a diagnostic code, an operation or a type
schema Print a JSON Schema published by tungsten
init Write tungsten.yml and agent.yml for a new project
doctor Report installed tools and optionally check project prerequisites
emitters List the external emitters (`tungsten-emit-<name>`) that can be run, with the protocol and version each reports
generate Generate every configured target (SDKs, docs) from the project
mock Serve a mock of the API from the compiled IR
report Coverage, safety matrix, token budgets, diagnostics and changes since the last generation, as text, one static HTML file or JSON
diff Show what regeneration would add, change or remove in each target, and with --semver how the API surface changed
overlay OpenAPI Overlay authoring helpers
lsp Serve a Language Server Protocol server on stdin and stdout for tungsten.yml, agent.yml and overlays: diagnostics, completion, hover, go-to-definition and symbols. `--json` has no effect
help Print this message or the help of the given subcommand(s)
Options:
--json
Print exactly one JSON document on stdout
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
Examples:
tungsten init --from openapi.yaml Write tungsten.yml and agent.yml
tungsten check . Validate the project and print diagnostics
tungsten generate --target ts,py Generate the TypeScript and Python SDKs
tungsten generate --target webmcp Generate a browser WebMCP adapter
tungsten mock --port 4010 Serve a mock of the API from the IR
tungsten report --html report.html Write a static coverage and safety report
tungsten diff --semver Show how the API surface changed
tungsten overlay suggest --write fixes.overlay.yaml
Suggest an overlay that fixes diagnostics
tungsten lsp Serve diagnostics, completion and hover for
manifests to an editor over stdio
Repository: https://github.com/pboachie/tungsten
Exit codes:
0 success (also `diff` when regeneration would change files, and
`report` with warnings)
1 the input has errors (or warnings with --strict), generated output is
stale (generate --check, check --ci), or the item asked for does not
exist (explain target not found, unknown target)
2 usage error: the command line could not be parsed
3 I/O or internal failure (for example --out is not writable, or the
mock server cannot start)
4 the command refused to act without confirmation (init over existing
files, generate into a directory tungsten did not write: pass --force)
Output:
Without --json, results go to stdout and diagnostics to stderr. With
--json, stdout carries exactly one JSON document described by
`tungsten schema cli-output`, help and version included. Color is used
only on a terminal and never when NO_COLOR is set.
tungsten check
Validate the manifest and specs and report diagnostics
Usage: tungsten check [OPTIONS] [PATH]
Arguments:
[PATH] A directory with a tungsten.yml, a tungsten*.yml manifest, or a single OpenAPI document [default: .]
Options:
--ci CI mode: never prompt, never color, and fail (TG0901) when the generated output of a target differs from what `generate` would write
--json Print exactly one JSON document on stdout
--strict Treat warnings as errors
-h, --help Print help
tungsten ir
Intermediate representation commands
Usage: tungsten ir [OPTIONS] <COMMAND>
Commands:
dump Write the IR as JSON
help Print this message or the help of the given subcommand(s)
Options:
--json Print exactly one JSON document on stdout
-h, --help Print help
tungsten ir dump
Write the IR as JSON
Usage: tungsten ir dump [OPTIONS] [PATH]
Arguments:
[PATH] A directory with a tungsten.yml, a tungsten*.yml manifest, or a single OpenAPI document [default: .]
Options:
--json Print exactly one JSON document on stdout
--out <FILE> Write the IR to this file instead of stdout
--compact One line instead of indented JSON
--pretty Indented JSON (the default)
-h, --help Print help
tungsten explain
Explain a diagnostic code, an operation or a type
Usage: tungsten explain [OPTIONS] <TARGET>
Arguments:
<TARGET> A diagnostic code (TG0201), an operation id (public.listPets) or a type id (public.Pet). A bare operationId or type name is accepted when it is unambiguous
Options:
--json Print exactly one JSON document on stdout
--project <PATH> Project used to resolve operation and type ids [default: .]
-h, --help Print help
tungsten schema
Print a JSON Schema published by tungsten
Usage: tungsten schema [OPTIONS] <NAME>
Arguments:
<NAME>
Which schema to print
Possible values:
- tungsten: The tungsten.yml manifest
- agent: The agent.yml manifest
- ir: The intermediate representation written by `ir dump`
- cli-output: The `--json` output of this CLI
- external-emitter: The documents of the external emitter protocol
- sdk-descriptors: The SDK descriptor document (tungsten_emit::sdk::descriptors)
- tool-catalog: Transport-neutral tools and scoped groups
Options:
--json
Print exactly one JSON document on stdout
-h, --help
Print help (see a summary with '-h')
tungsten init
Write tungsten.yml and agent.yml for a new project
Usage: tungsten init [OPTIONS]
Options:
--from <SPEC> OpenAPI document to start from. Default: openapi.json, openapi.yaml or openapi.yml in the target directory
--json Print exactly one JSON document on stdout
--dir <DIR> Directory to write the manifests into (created if missing) [default: .]
--name <NAME> API machine name: lowercase letters, digits and underscores, starting with a letter. Default: derived from the spec title
--targets <TARGETS> Targets to configure, comma-separated or repeated (ts, py, rs aliases). Default: typescript,python,docs. WebMCP also configures TypeScript
--force Overwrite existing tungsten.yml and agent.yml
-h, --help Print help
tungsten doctor
Report installed tools and optionally check project prerequisites
Usage: tungsten doctor [OPTIONS] [PATH]
Arguments:
[PATH] Project directory or tungsten manifest to inspect without network access
Options:
--json Print exactly one JSON document on stdout
--strict Fail when the project's required tools are missing or unsupported. Uses the current directory when PATH is omitted
-h, --help Print help
tungsten emitters
List the external emitters (`tungsten-emit-<name>`) that can be run, with the protocol and version each reports
Usage: tungsten emitters [OPTIONS] [PATH]
Arguments:
[PATH] A project (as for `check`) whose `external` targets are listed too
Options:
--json Print exactly one JSON document on stdout
-h, --help Print help
tungsten generate
Generate every configured target (SDKs, docs) from the project
Usage: tungsten generate [OPTIONS] [PATH]
Arguments:
[PATH] A directory with a tungsten.yml, a tungsten*.yml manifest, or a single OpenAPI document [default: .]
Options:
--json Print exactly one JSON document on stdout
--target <TARGETS> Only these targets, comma-separated (`typescript,docs`; `ts`, `py` and `rs` are accepted). Default: every target in tungsten.yml
--dry-run Report what would be written or removed without touching the disk
--check Compare the output directories with what would be generated; write nothing and exit 1 when they differ
--force Write into a non-empty output directory that tungsten did not generate (one without .tungsten/manifest.json)
--strict Treat warnings (the compiler's and the emitters') as errors: nothing is written when there are any, in any target
-h, --help Print help
tungsten mock
Serve a mock of the API from the compiled IR
Usage: tungsten mock [OPTIONS] [PATH]
Arguments:
[PATH] A directory with a tungsten.yml, a tungsten*.yml manifest, or a single OpenAPI document [default: .]
Options:
--json Print exactly one JSON document on stdout
--port <PORT> Port on 127.0.0.1 to listen on; 0 picks a free port [default: 0]
--seed <SEED> Seed for generated response values; the same seed gives the same responses [default: 0]
--gate <ENV> Treat this runtime gate (its environment variable, e.g. SEALED_WEBHOOK_DELIVERY_ENABLED) as on; repeat for several. Gates not listed keep their default
--max-recorded-calls <N> Recorded calls kept for `/__tungsten/calls`; past it the oldest is dropped. 0 records nothing [default: 10000]
--max-idempotent-responses <N> Stored idempotent responses kept for replays; past it the oldest is dropped and a later request with its key is served as new. 0 stores nothing [default: 10000]
-h, --help Print help
tungsten report
Coverage, safety matrix, token budgets, diagnostics and changes since the last generation, as text, one static HTML file or JSON
Usage: tungsten report [OPTIONS] [PATH]
Arguments:
[PATH] A directory with a tungsten.yml, a tungsten*.yml manifest, or a single OpenAPI document [default: .]
Options:
--html <FILE> Write the report as one static HTML file (no external assets, no scripts)
--json Print exactly one JSON document on stdout
-h, --help Print help
tungsten diff
Show what regeneration would add, change or remove in each target, and with --semver how the API surface changed
Usage: tungsten diff [OPTIONS] [PATH]
Arguments:
[PATH] A directory with a tungsten.yml, a tungsten*.yml manifest, or a single OpenAPI document [default: .]
Options:
--json Print exactly one JSON document on stdout
--target <TARGETS> Only these targets, comma-separated. Default: every target in tungsten.yml
--semver Classify the API surface change since the last generation (from .tungsten/surface.json) as major, minor, patch or none
--migration Include actionable migration guidance (implies --semver)
-h, --help Print help
tungsten overlay
OpenAPI Overlay authoring helpers
Usage: tungsten overlay [OPTIONS] <COMMAND>
Commands:
suggest Suggest an Overlay 1.0 document whose actions fix diagnostics (a missing or repeated operationId) without changing the IR
help Print this message or the help of the given subcommand(s)
Options:
--json Print exactly one JSON document on stdout
-h, --help Print help
tungsten overlay suggest
Suggest an Overlay 1.0 document whose actions fix diagnostics (a missing or repeated operationId) without changing the IR
Usage: tungsten overlay suggest [OPTIONS] [PATH]
Arguments:
[PATH] A directory with a tungsten.yml, a tungsten*.yml manifest, or a single OpenAPI document [default: .]
Options:
--json Print exactly one JSON document on stdout
--write <FILE> Write the overlay to this file instead of stdout
--force Overwrite the --write file if it exists
--only <CODES> Only suggest fixes for these diagnostic codes, comma-separated
--namespace <NAME> The input (namespace) to suggest for. Needed when more than one input has suggestions: an overlay's targets only fit its own spec
-h, --help Print help
tungsten lsp
Serve a Language Server Protocol server on stdin and stdout for tungsten.yml, agent.yml and overlays: diagnostics, completion, hover, go-to-definition and symbols. `--json` has no effect
Usage: tungsten lsp [OPTIONS]
Options:
--config <PATH> The manifest to serve: a tungsten.yml, or a directory holding one. Default: the tungsten.yml of the editor's workspace folder
--json Print exactly one JSON document on stdout
-h, --help Print help