[{"href":"/cli","title":"Use Lingua without opening a window","description":"Meet the headless Lingua CLI, build it today, and turn a first command into a repeatable local workflow.","group":"start","searchText":"Use Lingua without opening a window Meet the headless Lingua CLI, build it today, and turn a first command into a repeatable local workflow. install npm terminal quickstart headless offline help The Lingua CLI is for the moment when a useful action needs to leave the app and become a terminal command, a shell pipe, or a CI step. It runs the same utility adapters and Run Capsule schema as Lingua, but it does   not   start Electron or React.\n\nIt is local, scriptable, and intentionally small. Use it to format a payload on stdin, execute a trusted source file, validate a Capsule in CI, or replay a captured run.\n\n   Install it\n\n @linguacode/cli  is published on npm. It has no dependencies and needs Node 24.x:\n\n   bash\nnpm install -g @linguacode/cli\nlingua --help\n   \n\nPrefer not to install anything? Run it once with  npx :\n\n   bash\nnpx @linguacode/cli --help\n   \n\nMachines without Node can use the standalone  lingua-cli- -linux-x64.tar.gz  and  -windows-x64.tar.gz  archives attached to every stable  GitHub Release  https://github.com/johnny4young/lingua/releases/latest .\n\n   Build it from source\n\nContributors, and anyone tracking  main  ahead of a release, build from the repository:\n\n   bash\ngit clone https://github.com/johnny4young/lingua.git\ncd lingua\ncorepack enable\npnpm install\npnpm run build:cli\nnode dist/cli/lingua.cjs --help\n   \n\nFor local development, expose the  lingua  command on your  PATH :\n\n   bash\npnpm link --global\nlingua --version\n   \n\nThis link points at your checkout. Run  pnpm run build:cli  after changing CLI source.\n\n   Run your first useful command\n\nFormat JSON directly from another program:\n\n   bash\ncurl -s https://api.github.com/repos/johnny4young/lingua \\\n  | lingua utility json-format\n   \n\nOr run a source file through the toolchain already installed on your machine:\n\n   bash\nlingua run ./scripts/check.ts -- --verbose\n   \n\nEverything after  --  belongs to your program, not Lingua.\n\n   Choose the right command\n\n| You want to… | Start with |\n| --- | --- |\n| transform or inspect one value |  lingua utility  |\n| execute a file or conventional project |  lingua run  |\n| check a Capsule without running it |  lingua capsule validate  |\n| reproduce a captured single-file run |  lingua capsule replay  |\n| discover utilities and their options |  lingua list utilities --json  |\n| enable tab completion |  lingua completion  |\n\n   A safe mental model\n\nThe CLI never interpolates your command through a shell, but code executed by  lingua run  still has your operating-system permissions. Run only code you trust. For untrusted code, place the CLI inside a container or sandbox you control.\n\nThe CLI itself does not need a network. Your program can still use the network, and a missing language toolchain remains a local setup requirement.\n\n   Continue by task\n\n-  Run files and projects  /cli/run-code \n-  Pipe through developer utilities  /cli/utilities \n-  Validate and replay Run Capsules  /cli/capsules \n-  Use Lingua in scripts and CI  /cli/automation \n-  Fix PATH, runtime, and output problems  /cli/troubleshooting \n-  Review every command, flag, and exit code  /cli/reference  "},{"href":"/cli/run-code","title":"Run files and projects","description":"Execute trusted JavaScript, TypeScript, Python, Go, Rust, Ruby, or Lua with explicit stdin, arguments, timeouts, and environment values.","group":"guides","searchText":"Run files and projects Execute trusted JavaScript, TypeScript, Python, Go, Rust, Ruby, or Lua with explicit stdin, arguments, timeouts, and environment values. run project stdin argv timeout env javascript typescript python go rust ruby lua  lingua run  turns a source file or conventional project directory into one predictable command. Lingua selects an installed host runtime, starts it without a shell, bounds output, and owns the timeout.\n\n   Run one file\n\n   bash\nlingua run ./hello.js\nlingua run ./analysis.py\nlingua run ./hello.go\nlingua run ./hello.rs --timeout 60000\n   \n\nJavaScript and TypeScript use Node.js. Python, Go, Rust, Ruby, and Lua use their matching command-line toolchains. If a runtime is missing, Lingua exits with code 3 and names the missing capability.\n\n   Pass stdin without a fragile pipe\n\nUse  --stdin  when the input already lives in a file:\n\n   bash\nlingua run ./normalize.py --stdin fixtures/raw.txt\n   \n\nA normal pipe also works:\n\n   bash\nprintf 'Ada\\nGrace\\n' | lingua run ./greet.js\n   \n\nAn interactive terminal sends EOF when there is no pipe, so a program that reads stdin does not hang waiting for invisible input.\n\n   Forward program arguments\n\nPlace Lingua options before  -- . Every later token reaches the target unchanged:\n\n   bash\nlingua run ./scripts/check.ts --timeout 45000 -- --verbose --fix src\n   \n\nThis is the workaround when your program has an option named  --json  or  --quiet ; after the separator, those flags belong to the program.\n\n   Add explicit environment values\n\n   bash\nlingua run ./worker.py \\\n  --env MODE=development \\\n  --env FEATURE X=enabled\n   \n\n --env  is repeatable. Lingua does not blindly inherit every parent variable, and it blocks dynamic-loader injection keys plus  NODE OPTIONS . Pass secrets only when the program genuinely needs them; command histories and CI logs can expose arguments.\n\n   Run a conventional project\n\n   bash\nlingua run ./my-project\n   \n\nDetection follows a fixed order:\n\n1.  package.json :  scripts.start , then  scripts.dev , then a valid  main .\n2.  go.mod :  go run . .\n3.  Cargo.toml :  cargo run --quiet -- .\n4. Conventional entries such as  main.py ,  index.js , or  src/index.ts .\n\nIf a framework requires a special launcher, run that launcher yourself or point Lingua at an independently runnable source file. Lingua does not guess framework-specific commands.\n\n   Make automation deterministic\n\nUse  --json  when another program consumes the result and inspect the process exit code:\n\n   bash\nif result=$ lingua run ./healthcheck.ts --json ; then\n  printf '%s\\n' \"$result\" | jq -r '.run.stdout'\nelse\n  printf '%s\\n' \"$result\" | jq -r '.reason'  &2\nfi\n   \n\nPlain mode streams while the program runs. JSON mode buffers the same bounded output into one parseable document. "},{"href":"/cli/utilities","title":"Pipe through developer utilities","description":"Discover utility ids, transform stdin or files, pass adapter options, and keep shell pipelines predictable.","group":"guides","searchText":"Pipe through developer utilities Discover utility ids, transform stdin or files, pass adapter options, and keep shell pipelines predictable. utility pipe input option json-format base64 regex list utilities  lingua utility  brings focused transformations to the terminal. The adapters are shared with Lingua's developer-utilities panels, but the CLI keeps the contract text-based and automation-friendly.\n\n   Discover before you guess\n\n   bash\nlingua list utilities\nlingua list utilities --json | jq '.utilities   |  id, options '\n   \n\nThe JSON registry is the safest way for scripts to discover ids, input/output kinds, and accepted options.\n\n   Read from stdin\n\n   bash\necho ' \"team\": \"Ada\",\"Grace\"  ' | lingua utility json-format\nprintf 'hello world' | lingua utility base64-encode\n   \n\nStdin makes utilities compose naturally with  curl ,  git ,  jq , and other programs.\n\n   Read a file\n\n   bash\nlingua utility json-format --input package.json --option indent=4\nlingua utility base64-encode --input README.md\n   \n\n --input  belongs only to  utility . For an executed program's stdin, use  lingua run --stdin  instead.\n\n   Repeat adapter options\n\n   bash\nlingua utility regex-replace --input src.ts \\\n  --option pattern='console\\\\.log' \\\n  --option flags=g \\\n  --option replacement=logger.info\n   \n\nEach  --option  accepts one  key=value  pair. Quote values that contain spaces or shell metacharacters so your shell passes one argument.\n\n   Keep pipelines clean\n\n --quiet  removes Lingua diagnostics but preserves successful output:\n\n   bash\nlingua utility json-format --input raw.json --quiet   normalized.json\n   \n\nUse  --json  for a structured Lingua envelope, not when you want the transformed bytes directly:\n\n   bash\nlingua utility json-format --input raw.json --json | jq -r '.value'\n   \n\nBinary utility output is intentionally unsupported in this headless text contract and exits with code 3 rather than corrupting a terminal stream. "},{"href":"/cli/capsules","title":"Validate and replay Run Capsules","description":"Check a RunCapsuleV1 safely, replay trusted single-source captures, and understand integrity and workspace boundaries.","group":"guides","searchText":"Validate and replay Run Capsules Check a RunCapsuleV1 safely, replay trusted single-source captures, and understand integrity and workspace boundaries. capsule validate replay RunCapsuleV1 hash comparison workspace trust Run Capsules preserve one source buffer, input, arguments, environment metadata, and recorded output. The CLI can validate that contract or replay its single source through a local runtime.\n\n   Validate without executing\n\n   bash\nlingua capsule validate ./run.capsule.json\nlingua capsule validate ./run.capsule.json --json\n   \n\nValidation checks the 4 MiB limit, JSON syntax, schema version, migrations, required fields, and field types. It never executes the stored source.\n\nUse this form in an upload or build gate:\n\n   bash\nfor capsule in build/ .capsule.json; do\n  lingua capsule validate \"$capsule\" --quiet || exit 1\ndone\n   \n\n   Replay trusted source\n\n   bash\nlingua capsule replay ./run.capsule.json\nlingua capsule replay ./run.capsule.json --timeout 60000 --json\n   \n\nReplay first verifies that  source.content  matches its recorded SHA-256 hash. It then executes the source and compares status, stdout, and stderr with the recorded result.\n\nA successful command may still report  comparison.matches: false . That is useful reproducibility evidence, not a runtime failure.\n\n   Know the trust boundary\n\nThe content hash detects accidental inconsistency. It is   not a signature  : someone editing the file can replace the source and recompute its hash. Replay only Capsules from sources you trust because their code receives your current operating-system permissions.\n\nBrowser-preview Capsules are not replayable in a headless process, and missing runtimes exit with code 3 instead of silently changing execution mode.\n\n   Capsule Workspace workaround\n\n CapsuleWorkspaceV1  can carry explicitly selected supplemental text files for read-only handoff in the app. The CLI does not reconstruct or replay that multi-file wrapper.\n\n- If the nested Capsule is independently runnable, extract and replay that single source.\n- If it depends on sibling files, use  lingua run  project-directory   against the actual project. "},{"href":"/cli/automation","title":"Automate with stable output","description":"Use JSON envelopes, quiet mode, exit codes, completions, and bounded execution to make scripts and CI jobs dependable.","group":"automation","searchText":"Automate with stable output Use JSON envelopes, quiet mode, exit codes, completions, and bounded execution to make scripts and CI jobs dependable. ci automation json quiet exit code completion bash zsh fish no color The CLI separates data on stdout from human diagnostics on stderr. Add stable exit codes,  --json , and bounded execution, and it becomes a dependable CI building block.\n\n   Pick plain text or JSON deliberately\n\nPlain mode is best when Lingua's output is the next program's input:\n\n   bash\nlingua utility json-format --input raw.json --quiet   normalized.json\n   \n\nJSON mode is best when a script needs status and metadata:\n\n   bash\nresult=$ lingua run ./check.ts --json  || status=$?\nprintf '%s\\n' \"$result\" | jq .\nexit \"$ status:-0 \"\n   \n\nStructured output never contains ANSI escapes, even if  --color=always  is present.\n\n   Depend on exit-code families\n\n| Code | Meaning | Typical response |\n| --- | --- | --- |\n| 0 | success | continue |\n| 1 | invalid arguments or input | fix the invocation or artifact |\n| 2 | runtime failure or timeout | inspect program output |\n| 3 | unsupported or missing capability | install/choose a runtime |\n| 4 | unexpected internal failure | capture diagnostics and report it |\n\n   Prevent stuck jobs\n\n   bash\nlingua run ./integration-check.py --timeout 90000 --json\n   \n\nThe allowed range is 100–300000 ms, with a 30000 ms default. Timeout and Ctrl+C terminate the subprocess tree.\n\n   Install shell completion\n\n    Bash\n\n   bash\nmkdir -p ~/.local/share/bash-completion/completions\nlingua completion bash   ~/.local/share/bash-completion/completions/lingua\n   \n\n    Zsh\n\n   zsh\nmkdir -p ~/.zfunc\nlingua completion zsh   ~/.zfunc/ lingua\nfpath= ~/.zfunc $fpath \nautoload -Uz compinit && compinit\n   \n\n    Fish\n\n   fish\nmkdir -p ~/.config/fish/completions\nlingua completion fish   ~/.config/fish/completions/lingua.fish\n   \n\nCompletion generation is deterministic and network-free, so package scripts can install it without contacting a service. "},{"href":"/cli/troubleshooting","title":"Troubleshoot the CLI","description":"Resolve command-not-found, missing toolchain, timeout, argument, Capsule, color, and output issues without hiding failures.","group":"automation","searchText":"Troubleshoot the CLI Resolve command-not-found, missing toolchain, timeout, argument, Capsule, color, and output issues without hiding failures. troubleshooting PATH command not found missing runtime timeout invalid arguments no color output Start with the exact exit code and the stable reason inside  error ...   or the JSON envelope. They distinguish user input, runtime failures, and unavailable capabilities.\n\n   The lingua command is not found\n\nWhen working from source, rebuild and link from the repository root:\n\n   bash\npnpm run build:cli\npnpm link --global\ncommand -v lingua\nlingua --version\n   \n\nIf  pnpm link --global  succeeds but your shell cannot find the command, inspect  pnpm bin --global  and add that directory to your shell's  PATH . Restart the shell after changing its profile.\n\n   A runtime is missing\n\nConfirm that the same shell can find the toolchain:\n\n   bash\nnode --version\npython3 --version\ngo version\nrustc --version\nruby --version\nlua -v\n   \n\nDesktop applications and login shells can inherit different PATH values. The CLI uses the environment of the shell that launched it, so test in that exact terminal.\n\n   My program flag is rejected by Lingua\n\nSeparate the two argument domains:\n\n   bash\nlingua run ./server.ts --timeout 60000 -- --json --port 4000\n   \n\nBefore  -- , options belong to Lingua. After it, every token belongs to your program.\n\n   The command timed out\n\nIncrease the limit within the 100–300000 ms range:\n\n   bash\nlingua run ./slow-analysis.py --timeout 120000\n   \n\nIf the target is a long-running server, run its framework command directly. Lingua's bounded run command is designed for tasks that eventually finish.\n\n   Output was truncated\n\nEach stdout and stderr stream has a 1 MiB budget. Reduce verbose output, write large results to a file from the target program, or divide the work.  --json  does not increase the budget.\n\n   CI logs contain color codes\n\n   bash\nNO COLOR=1 lingua run ./check.ts\nlingua run ./check.ts --color=never\n   \n\n --color=never  wins explicitly. JSON and completion output are always unstyled.\n\n   A Capsule validates but replay differs\n\nValidation proves the file matches the schema; it does not promise deterministic program behavior. Time, random values, local dependencies, network responses, and toolchain versions can change output. Inspect  comparison  in JSON mode rather than treating every mismatch as CLI failure. "},{"href":"/cli/reference","title":"Command and option reference","description":"Scan every Lingua CLI command, shared option, limit, output mode, and stable exit code in one place.","group":"reference","searchText":"Command and option reference Scan every Lingua CLI command, shared option, limit, output mode, and stable exit code in one place. reference command flag option exit codes help version color quiet json This reference follows the same structured catalog used to generate  lingua --help . The website build fails if its committed catalog snapshot drifts from the CLI source.\n\n   Commands\n\n| Command | Purpose |\n| --- | --- |\n|  lingua utility  utility-id   | Run one shared developer-utility adapter. |\n|  lingua capsule validate  file   | Validate a  RunCapsuleV1  without execution. |\n|  lingua capsule replay  file   | Verify and replay a trusted single-source Capsule. |\n|  lingua run  file-or-directory   | Execute a source file or conventional project root. |\n|  lingua list utilities  | Print the live utility registry. |\n|  lingua completion bash\\|zsh\\|fish  | Generate shell completion source. |\n|  lingua --version  | Print the build-time CLI version. |\n|  lingua --help  | Print terminal help. |\n\n   Options\n\n| Option | Used by | Meaning |\n| --- | --- | --- |\n|  --input  file   |  utility  | Read utility input from a file instead of stdin. |\n|  --option key=value  |  utility  | Repeat to pass adapter-specific options. |\n|  --stdin  file   |  run  | Forward file contents as program stdin. |\n|  --timeout  ms   |  run ,  capsule replay  | Stop after 100–300000 ms. |\n|  --env NAME=value  |  run ,  capsule replay  | Repeat to add an explicit environment value. |\n|  --json  | data-producing commands | Emit one structured JSON document. |\n|  --quiet  | data-producing commands | Suppress Lingua diagnostics, not command output. |\n|  --color  auto\\|always\\|never   | all commands | Control human diagnostic styling. |\n|  --  |  run  | Forward every remaining token to the program. |\n|  --help ,  -h  | all commands | Show help. |\n|  --version ,  -v  | top level | Print the CLI version. |\n\n   Exit codes\n\n| Code | Name | Meaning |\n| --- | --- | --- |\n| 0 |  ok  | Command completed successfully. |\n| 1 |  userInputError  | Arguments, input, file, or shape are invalid. |\n| 2 |  runtimeError  | Execution failed, timed out, stopped, or exited non-zero. |\n| 3 |  unsupportedCapability  | Runtime, mode, toolchain, or output is unsupported. |\n| 4 |  internal  | An unexpected exception reached the CLI boundary. |\n\n   Output contract\n\nHuman failures use a grep-friendly form:\n\n   text\nlingua run: error missing-runtime : Required runtime \"lua\" is not available on PATH.\n   \n\nWith  --json , the same stable reason moves to stdout:\n\n   json\n \n  \"ok\": false,\n  \"reason\": \"missing-runtime\",\n  \"detail\": \"Required runtime \\\"lua\\\" is not available on PATH.\"\n \n   \n\nCommand-specific success envelopes are documented in the task guides. Existing exit codes are never renumbered.  \"schemaVersion\":1,\"title\":\"lingua — local code runner CLI\",\"commands\":  \"id\":\"utility\",\"topLevel\":\"utility\",\"invocation\":\"lingua utility  utility-id   --input  file    --json   --quiet   --option key=value ... \",\"summary\":\"Run a focused developer utility from a pipe or file.\",\"description\":\"Uses the same shared utility adapters as the desktop app without loading Electron or a renderer.\",\"flags\": \"input\",\"option\",\"json\",\"quiet\",\"color\",\"help\" ,\"examples\":  \"command\":\"echo ' \\\"a\\\":1 ' | lingua utility json-format\",\"description\":\"Format piped JSON.\" , \"command\":\"lingua utility base64-encode --input README.md\",\"description\":\"Encode a file without opening the app.\"   , \"id\":\"capsule-validate\",\"topLevel\":\"capsule\",\"invocation\":\"lingua capsule validate  file   --json   --quiet \",\"summary\":\"Validate a RunCapsuleV1 file without executing it.\",\"description\":\"Checks size, JSON shape, schema compatibility, and required fields through the same validator used by Lingua.\",\"flags\": \"json\",\"quiet\",\"color\",\"help\" ,\"examples\":  \"command\":\"lingua capsule validate ./run.capsule.json\",\"description\":\"Validate a capsule for a person reading terminal output.\" , \"command\":\"lingua capsule validate ./run.capsule.json --json\",\"description\":\"Return a stable machine-readable result.\"   , \"id\":\"capsule-replay\",\"topLevel\":\"capsule\",\"invocation\":\"lingua capsule replay  file   --timeout  ms    --env NAME=value ...   --json   --quiet \",\"summary\":\"Verify and replay the single source stored in a Run Capsule.\",\"description\":\"Verifies the recorded source hash, executes through the matching local runtime, and compares the fresh result with the recording.\",\"flags\": \"timeout\",\"env\",\"json\",\"quiet\",\"color\",\"help\" ,\"examples\":  \"command\":\"lingua capsule replay ./run.capsule.json --json\",\"description\":\"Replay and inspect the comparison envelope.\"   , \"id\":\"run\",\"topLevel\":\"run\",\"invocation\":\"lingua run  file-or-directory   --stdin  file    --timeout  ms    --env NAME=value ...   --json   --quiet   -- args... \",\"summary\":\"Run a source file or conventional project root.\",\"description\":\"Executes trusted code with installed host toolchains, bounded output, a parent-owned timeout, and no shell interpolation.\",\"flags\": \"stdin\",\"timeout\",\"env\",\"json\",\"quiet\",\"color\",\"separator\",\"help\" ,\"examples\":  \"command\":\"lingua run ./script.py --stdin input.txt -- --verbose\",\"description\":\"Run Python with file-backed stdin and a forwarded argument.\" , \"command\":\"lingua run ./my-project --timeout 60000\",\"description\":\"Detect and run a conventional project root.\"   , \"id\":\"list-utilities\",\"topLevel\":\"list\",\"invocation\":\"lingua list utilities  --json   --quiet \",\"summary\":\"Discover utility ids, input kinds, output kinds, and options.\",\"description\":\"Prints the live utility registry so people and scripts do not need to guess adapter names or supported options.\",\"flags\": \"json\",\"quiet\",\"color\",\"help\" ,\"examples\":  \"command\":\"lingua list utilities --json\",\"description\":\"Inspect the registry from a script.\"   , \"id\":\"completion\",\"topLevel\":\"completion\",\"invocation\":\"lingua completion bash|zsh|fish\",\"summary\":\"Generate a deterministic shell completion script.\",\"description\":\"Prints network-free Bash, Zsh, or Fish completion source without ANSI styling.\",\"flags\": \"color\",\"help\" ,\"examples\":  \"command\":\"lingua completion zsh   ~/.zfunc/ lingua\",\"description\":\"Install the Zsh completion file.\"    ,\"flags\":  \"id\":\"input\",\"syntax\":\"--input  file \",\"summary\":\"Read utility input from a file instead of stdin.\",\"commands\": \"utility\"  , \"id\":\"stdin\",\"syntax\":\"--stdin  file \",\"summary\":\"Forward a file as program stdin.\",\"commands\": \"run\"  , \"id\":\"timeout\",\"syntax\":\"--timeout  ms \",\"summary\":\"Stop run or replay after 100–300000 ms.\",\"commands\": \"run\",\"capsule-replay\"  , \"id\":\"env\",\"syntax\":\"--env NAME=value\",\"summary\":\"Repeat to add an explicit child-process environment value.\",\"commands\": \"run\",\"capsule-replay\"  , \"id\":\"option\",\"syntax\":\"--option key=value\",\"summary\":\"Repeat to pass an adapter option.\",\"commands\": \"utility\"  , \"id\":\"json\",\"syntax\":\"--json\",\"summary\":\"Emit a stable structured JSON body instead of plain text.\",\"commands\": \"utility\",\"capsule-validate\",\"capsule-replay\",\"run\",\"list-utilities\"  , \"id\":\"quiet\",\"syntax\":\"--quiet\",\"summary\":\"Suppress Lingua diagnostics while preserving command output.\",\"commands\": \"utility\",\"capsule-validate\",\"capsule-replay\",\"run\",\"list-utilities\"  , \"id\":\"color\",\"syntax\":\"--color  auto|always|never \",\"summary\":\"Control diagnostic color. The default is auto.\",\"commands\": \"utility\",\"capsule-validate\",\"capsule-replay\",\"run\",\"list-utilities\",\"completion\"  , \"id\":\"separator\",\"syntax\":\"--\",\"summary\":\"Forward every remaining token to the executed program unchanged.\",\"commands\": \"run\"  , \"id\":\"help\",\"syntax\":\"--help, -h\",\"summary\":\"Show help.\",\"commands\": \"utility\",\"capsule-validate\",\"capsule-replay\",\"run\",\"list-utilities\",\"completion\"  , \"id\":\"version\",\"syntax\":\"--version, -v\",\"summary\":\"Print the CLI version.\",\"commands\":    ,\"exitCodes\":  \"code\":0,\"name\":\"ok\",\"summary\":\"Command completed successfully.\" , \"code\":1,\"name\":\"userInputError\",\"summary\":\"Arguments, input, file, or shape are invalid.\" , \"code\":2,\"name\":\"runtimeError\",\"summary\":\"Execution failed, timed out, stopped, or exited non-zero.\" , \"code\":3,\"name\":\"unsupportedCapability\",\"summary\":\"Runtime, mode, toolchain, or output is unsupported.\" , \"code\":4,\"name\":\"internal\",\"summary\":\"An unexpected exception reached the CLI boundary.\"   "}]

Lingua CLI

Validate and replay Run Capsules

Check a RunCapsuleV1 safely, replay trusted single-source captures, and understand integrity and workspace boundaries.

Search CLI documentation

Press / to search

Browse CLI guides

The CLI is published on npm as @linguacode/cli. Install it globally, run it with npx, or build it from source.

Run Capsules preserve one source buffer, input, arguments, environment metadata, and recorded output. The CLI can validate that contract or replay its single source through a local runtime.

Validate without executing

lingua capsule validate ./run.capsule.json
lingua capsule validate ./run.capsule.json --json

Validation checks the 4 MiB limit, JSON syntax, schema version, migrations, required fields, and field types. It never executes the stored source.

Use this form in an upload or build gate:

for capsule in build/*.capsule.json; do
  lingua capsule validate "$capsule" --quiet || exit 1
done

Replay trusted source

lingua capsule replay ./run.capsule.json
lingua capsule replay ./run.capsule.json --timeout 60000 --json

Replay first verifies that source.content matches its recorded SHA-256 hash. It then executes the source and compares status, stdout, and stderr with the recorded result.

A successful command may still report comparison.matches: false. That is useful reproducibility evidence, not a runtime failure.

Know the trust boundary

The content hash detects accidental inconsistency. It is not a signature: someone editing the file can replace the source and recompute its hash. Replay only Capsules from sources you trust because their code receives your current operating-system permissions.

Browser-preview Capsules are not replayable in a headless process, and missing runtimes exit with code 3 instead of silently changing execution mode.

Capsule Workspace workaround

CapsuleWorkspaceV1 can carry explicitly selected supplemental text files for read-only handoff in the app. The CLI does not reconstruct or replay that multi-file wrapper.

If the nested Capsule is independently runnable, extract and replay that single source.
If it depends on sibling files, use lingua run <project-directory> against the actual project.