[{"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 homebrew brew 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\nOn macOS, Homebrew downloads the release-owned CLI artifact and configures Node 24 for you. It does not invoke npm:\n\n   bash\nbrew install johnny4young/tap/lingua-cli\nlingua --help\n   \n\nThis is separate from  brew install --cask johnny4young/tap/lingua , which installs the same Desktop application distributed in the  .dmg  under  /Applications/lingua.app .\n\n @linguacode/cli  also remains available on npm for every Node-supported platform. It has no package 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-  Copy practical recipes for APIs, repositories, CI, containers, and PowerShell  /cli/recipes \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.\n\nFor option-aware examples covering APIs, JWTs, hashes, Unicode, identifiers,\ncron, source rewrites, and more, continue with  Practical recipes for everyday\ndevelopment  /cli/recipes . "},{"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/recipes","title":"Practical recipes for everyday development","description":"Copy working Lingua CLI patterns for APIs, data cleanup, local scripts, Git hooks, CI, containers, Capsules, Bash, and PowerShell.","group":"guides","searchText":"Practical recipes for everyday development Copy working Lingua CLI patterns for APIs, data cleanup, local scripts, Git hooks, CI, containers, Capsules, Bash, and PowerShell. recipes examples api curl jq git hook github actions npm scripts makefile docker powershell ci These recipes solve small, common developer tasks with commands you can copy and adapt. They assume  lingua --version  works and that every file or program you execute is trusted.\n\n   Pick a recipe by outcome\n\n| You need to… | Recipe |\n| --- | --- |\n| inspect an API response |  Format JSON from curl   format-json-from-curl  |\n| inspect a token without uploading it |  Read a JWT header and payload   read-a-jwt-header-and-payload  |\n| create a URL query safely |  Encode one URL component   encode-one-url-component  |\n| normalize generated files |  Guard JSON in a Git hook   guard-json-in-a-git-hook  |\n| run a repository check |  Expose Lingua through package.json   expose-lingua-through-packagejson  |\n| add a CI gate |  Pin the CLI in GitHub Actions   pin-the-cli-in-github-actions  |\n| reproduce a captured run |  Require an exact Capsule replay   require-an-exact-capsule-replay  |\n| use Lingua from Windows |  Keep the exit code in PowerShell   keep-the-exit-code-in-powershell  |\n\n   Work with API and web data\n\n    Format JSON from curl\n\nKeep the transformed JSON on stdout so it can continue into  jq :\n\n   bash\ncurl -fsSL https://api.github.com/repos/johnny4young/lingua \\\n  | lingua utility json-format --quiet \\\n  | jq ' name, stargazers count, open issues count '\n   \n\n curl -f  makes HTTP errors fail the pipeline. In Bash CI jobs, add  set -o pipefail  so an earlier failure cannot be hidden by a later command.\n\n    Minify a JSON release artifact\n\n   bash\nlingua utility json-minify --input config/runtime.json --quiet \\\n    dist/runtime.min.json\n   \n\nThe command parses before writing, so malformed JSON fails instead of producing a partially transformed artifact.\n\n    Read a JWT header and payload\n\n   bash\nprintf '%s' \"$ACCESS TOKEN\" \\\n  | lingua utility jwt-decode --quiet \\\n  | jq ' algorithm: .header.alg, subject: .payload.sub, expires: .payload.exp '\n   \n\nThis decodes local text only. It does   not   verify the signature, issuer, audience, expiry, or authorization. Never treat decoded claims as trusted identity.\n\n    Encode one URL component\n\n   bash\nquery=$ printf '%s' 'state:open label:\"good first issue\"' \\\n  | lingua utility url-encode --quiet \n\ncurl -fsSL \"https://api.github.com/search/issues?q=$ query \" | jq '.total count'\n   \n\n url-encode  is for a component such as one query value, not for re-encoding an entire URL.\n\n    Break an absolute URL into fields\n\n   bash\nprintf '%s' 'https://example.com:8443/api/items?limit=20 results' \\\n  | lingua utility url-parse --quiet \\\n  | jq ' origin, pathname, searchParams '\n   \n\n url-parse  rejects relative URLs deliberately. Resolve a relative path against its base before passing it to the utility.\n\n    Encode or decode text as Base64\n\n   bash\nencoded=$ printf '%s' 'local developer value' | lingua utility base64-encode --quiet \nprintf '%s' \"$encoded\" | lingua utility base64-decode --quiet\n   \n\nThe CLI contract is UTF-8 text. Base64 is an encoding, not encryption, and this recipe is not intended for arbitrary binary files or secrets.\n\n    Escape a snippet for safe HTML text\n\n   bash\nprintf '%s' ' button data-id=\"42\" Run & inspect /button ' \\\n  | lingua utility html-entity-encode --quiet\n   \n\nThis escapes text content. It does not sanitize an HTML document or make untrusted markup safe to execute.\n\n   Normalize text and developer data\n\n    Compute a text digest\n\n   bash\ndigest=$ lingua utility hash \\\n  --input release-notes.md \\\n  --option algorithm=SHA-256 \\\n  --quiet \nprintf 'release-notes.md  %s\\n' \"$digest\"\n   \n\nThe digest covers the UTF-8 text read by the CLI. Use an operating-system checksum tool when byte-for-byte hashing of arbitrary binary files is required.\n\n    Sort and deduplicate changed paths\n\n   bash\ngit diff --name-only origin/main...HEAD \\\n  | lingua utility line-sort \\\n      --option unique=true \\\n      --option caseInsensitive=true \\\n      --quiet\n   \n\nAdd  --option numeric=true  when values such as  fixture2  and  fixture10  should use natural ordering.\n\n    Produce a stable identifier style\n\n   bash\nprintf '%s' 'HTTP response cache key' \\\n  | lingua utility string-case --option target=snake --quiet\n\nprintf '%s' 'Guía rápida para equipos' \\\n  | lingua utility slugify --option separator=hyphen --quiet\n   \n\nUse  string-case  for code-oriented naming   camel ,  snake ,  kebab , and others . Use  slugify  for an ASCII URL or filename segment.\n\n    Replace a repeated source pattern\n\n   bash\nlingua utility regex-replace \\\n  --input src/legacy.ts \\\n  --option pattern='console\\\\.log' \\\n  --option flags=g \\\n  --option replacement=logger.info \\\n  --quiet   /tmp/legacy.updated.ts\n\ndiff -u src/legacy.ts /tmp/legacy.updated.ts\n   \n\nPreview the diff before replacing the original file. Quote the pattern so the shell does not interpret backslashes or metacharacters.\n\n    Inspect suspicious Unicode\n\n   bash\ngit log -1 --pretty=%B | lingua utility string-inspect --quiet\n   \n\nThe result distinguishes graphemes, code points, UTF-16 units, UTF-8 bytes, zero-width characters, and bidirectional controls—useful when two strings look identical but compare differently.\n\n    Convert a timestamp during incident review\n\n   bash\nprintf '%s' '1735689600' | lingua utility timestamp --quiet\n   \n\nThe result includes ISO 8601, epoch milliseconds, and epoch seconds. Record the original timezone separately when it matters; a Unix epoch represents an instant, not the author's timezone.\n\n    Convert an integer without losing precision\n\n   bash\nprintf '%s' '9007199254740993' \\\n  | lingua utility number-base \\\n      --option from=10 \\\n      --option to=16 \\\n      --option prefixOutput=true \\\n      --quiet\n   \n\nThe converter uses integer arithmetic rather than floating-point conversion, so values above JavaScript's safe-integer limit remain exact.\n\n    Generate test identifiers\n\n   bash\nprintf 'generator-input-is-ignored' \\\n  | lingua utility uuid \\\n      --option format=v7 \\\n      --option count=5 \\\n      --quiet\n   \n\n uuid  is a generator: it still receives stdin because every utility has one text-input contract, but it intentionally ignores that input. Generated values are not deterministic snapshots.\n\n    Translate a schedule into cron\n\n   bash\nprintf '%s' 'weekdays at 9:30' \\\n  | lingua utility cron-phrase --option annotate=true --quiet\n   \n\nKeep  annotate=true  while reviewing the expression: the extra comment lines surface assumptions and cron caveats. Test the final schedule in the timezone and cron implementation that will run it.\n\n    Inspect a design token color\n\n   bash\nprintf '%s' 'rgba 14, 165, 233, 0.75 ' \\\n  | lingua utility color-convert --quiet\n   \n\nThe output presents equivalent HEX, RGB/RGBA, and HSL forms for quick comparison.\n\n   Run repository tools consistently\n\n    Pass a fixture as stdin\n\n   bash\nlingua run ./scripts/normalize.py \\\n  --stdin ./fixtures/raw-event.json \\\n  --timeout 45000\n   \n\nUse  --stdin  when the input already has a path. It avoids a fragile shell pipeline and makes the fixture visible in the invocation.\n\n    Forward arguments to the program\n\n   bash\nlingua run ./scripts/check.ts \\\n  --timeout 60000 \\\n  -- --changed-only --format=json\n   \n\nEverything after  --  belongs to  check.ts . Lingua does not parse or reorder those tokens.\n\n    Run a conventional project root\n\n   bash\nlingua run ./tools/release-audit --timeout 120000\n   \n\nDirectory detection supports conventional  package.json ,  go.mod ,  Cargo.toml , and common single-file entry points. Run the framework command directly when a repository needs custom orchestration or a permanent server.\n\n    Expose Lingua through package.json\n\nPin the CLI in  devDependencies , then give collaborators one memorable script:\n\n   json\n \n  \"devDependencies\":  \n    \"@linguacode/cli\": \"1.3.0\"\n   ,\n  \"scripts\":  \n    \"check:local\": \"lingua run ./scripts/check.ts --timeout 60000 -- --changed-only\",\n    \"check:capsules\": \"lingua capsule validate ./artifacts/latest.capsule.json --quiet\"\n   \n \n   \n\n   bash\nnpm run check:local\n   \n\nCommit the lockfile. Upgrade the pinned version only after the same checks pass in your repository.\n\n    Add a Make target\n\n   make\n.PHONY: verify-fixtures\nverify-fixtures:\n\tlingua run ./scripts/verify-fixtures.py --stdin ./fixtures/events.ndjson --timeout 90000\n   \n\nThe recipe line must begin with a tab. Make preserves Lingua's exit code, so a failed run fails the target.\n\n    Guard JSON in a Git hook\n\nUse a temporary file instead of rewriting a staged file automatically:\n\n   bash\n !/usr/bin/env bash\nset -euo pipefail\n\ntmp=$ mktemp \ntrap 'rm -f \"$tmp\"' EXIT\n\nlingua utility json-format --input config/app.json --option indent=2 --quiet   \"$tmp\"\nif ! cmp -s config/app.json \"$tmp\"; then\n  echo 'config/app.json is not in canonical format'  &2\n  diff -u config/app.json \"$tmp\" || true\n  exit 1\nfi\n   \n\nInstall it with your repository's existing hook manager. Hooks can be bypassed, so keep the same invariant in CI.\n\n   Put Lingua in automation\n\n    Pin the CLI in GitHub Actions\n\n   yaml\nname: CLI checks\non:  pull request \n\njobs:\n  verify:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: 24\n          cache: npm\n      - run: npm ci\n      - run: npx --no-install lingua run ./scripts/check.ts --json\n      - run: npx --no-install lingua capsule validate ./artifacts/example.capsule.json --quiet\n   \n\nThis assumes  @linguacode/cli  is pinned in the repository and lockfile, as in the  package.json  recipe. Install each language toolchain explicitly when the target is not JavaScript or TypeScript.\n\n    Preserve structured output and the exit code\n\n   bash\n !/usr/bin/env bash\nset -uo pipefail\n\nresult=$ lingua run ./scripts/healthcheck.ts --json \nstatus=$?\n\nprintf '%s\\n' \"$result\" | jq .\nif    status != 0   ; then\n  printf 'Lingua failed with exit code %d\\n' \"$status\"  &2\nfi\nexit \"$status\"\n   \n\nDo not append  || true  to a gate unless failure is intentionally advisory. The JSON body explains the failure; the exit code decides whether automation continues.\n\n    Offer missing-runtime recovery without parsing prose\n\n   bash\nresult=$ lingua run ./worker.py --json \nstatus=$?\n\nif    status == 3   ; then\n  printf '%s\\n' \"$result\" | jq ' reason, recovery '  &2\nfi\nexit \"$status\"\n   \n\nExit code 3 means a capability is unavailable. The structured  recovery  object can contain the runtime, executable, install command or guide, and verification command.\n\n    Validate every Capsule artifact\n\n   bash\n !/usr/bin/env bash\nset -euo pipefail\n\nwhile IFS= read -r -d '' capsule; do\n  lingua capsule validate \"$capsule\" --quiet\ndone     find artifacts -name ' .capsule.json' -type f -print0 \n   \n\nThis validates shape and limits without executing stored source. Use  -print0  so filenames containing spaces remain one item;  set -e  stops on the first invalid artifact.\n\n    Require an exact Capsule replay\n\n   bash\nlingua capsule replay ./artifacts/release-check.capsule.json \\\n  --timeout 60000 \\\n  --json \\\n  | jq -e '.ok == true and .comparison.matches == true'\n   \n\nReplay itself can exit 0 when the program ran successfully but differed from the recorded result.  jq -e  turns exact comparison into an explicit CI policy. Replay only trusted Capsules.\n\n    Build a small container image\n\n   dockerfile\nFROM node:24-bookworm-slim\n\nRUN npm install --global @linguacode/cli@1.3.0\nWORKDIR /workspace\nENTRYPOINT  \"lingua\" \nCMD  \"--help\" \n   \n\n   bash\ndocker build -t local/lingua-cli .\ndocker run --rm -i local/lingua-cli utility json-format --quiet \\\n    fixtures/payload.json\n   \n\nMount trusted source plus the required language toolchain when using  lingua run . The container is the isolation boundary; Lingua is not an OS sandbox by itself.\n\n   Use native shell patterns\n\n    Bootstrap completion on a workstation\n\n   bash\nlingua completion --dry-run\nlingua completion\n   \n\nThe first command shows every detected shell and target file. The second asks once before writing. Homebrew installations place Bash, Zsh, and Fish completion files automatically.\n\n    Keep the exit code in PowerShell\n\n   powershell\n$result = lingua run .\\scripts\\check.ts --json | ConvertFrom-Json\n$status = $LASTEXITCODE\n\n$result | ConvertTo-Json -Depth 8\nif  $status -ne 0   \n  Write-Error \"Lingua failed with exit code $status\"\n \nexit $status\n   \n\nCapture  $LASTEXITCODE  immediately after  lingua ; another native command can replace it.\n\n    Format a file in PowerShell\n\n   powershell\nGet-Content .\\config\\app.json -Raw |\n  lingua utility json-format --option indent=4 --quiet |\n  Set-Content .\\config\\app.formatted.json -Encoding utf8\n\nif  $LASTEXITCODE -ne 0    exit $LASTEXITCODE  \n   \n\nWrite to a second file first. Review or compare it before replacing the original.\n\n   Discover what your installed version supports\n\nThe installed registry is the source of truth when scripts must work across CLI versions:\n\n   bash\nlingua list utilities --json \\\n  | jq -r '.utilities   |  .id,  .optionKeys | join \",\"    | @tsv'\n\nlingua --help\nlingua utility --help\nlingua run --help\n   \n\nPrefer discovery over guessing an adapter option. For stable automation, pin the CLI version and commit your package lockfile or immutable installer metadata. "},{"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\nHomebrew installs Bash, Zsh, and Fish completion files automatically. For\nother install channels, let Lingua detect the supported shells on  PATH , show\nthe exact target files, and ask once before writing:\n\n   bash\nlingua completion\nlingua completion --dry-run\nlingua completion install --yes   explicit non-interactive approval\n   \n\nThe installer marks the current shell, configures standard Bash and Fish user\ndirectories, and maintains one delimited Zsh block in  .zshrc . It refuses to\nwrite from CI or a pipe unless  --yes  is present.\n\nYou can still generate one deterministic script manually:\n\n   bash\nlingua completion bash\nlingua completion zsh\nlingua completion fish\n   \n\nCompletion generation is deterministic and network-free, so package scripts can install it without contacting a service.\n\nSee  Practical recipes for everyday development  /cli/recipes  for complete\nGitHub Actions, Git hook, package script, Make, Docker, Bash, and PowerShell\npatterns. "},{"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   Missing runtimes\n\nLingua now prints the runtime name, a platform-aware install action, a command\nto verify the setup, and this guide whenever  lingua run  cannot find a required\ntoolchain. On macOS the direct recovery commands are:\n\n   bash\nbrew install python    Python\nbrew install go        Go\nbrew install rust      Rust and Cargo\nbrew install ruby      Ruby\nbrew install lua       Lua\n   \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\nIn  --json  mode, inspect  run.recovery   also projected as top-level\n recovery   for  runtime ,  executable , optional  installCommand ,\n installGuide , and  verifyCommand  instead of parsing the human text.\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\\|install   | Detect and install completions, or generate one shell script. |\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|  --yes  |  completion  | Approve detected completion changes without prompting. |\n|  --dry-run  |  completion  | Show detected shells and target files without writing. |\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\":\"echo 'cada 3 dias 8am' | lingua utility cron-phrase\",\"description\":\"Turn a plain-words schedule  English or Spanish  into a cron expression.\" , \"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|install   --yes   --dry-run \",\"summary\":\"Install completions interactively or print one shell script.\",\"description\":\"With no target or with install, detects Bash, Zsh, and Fish, shows the target files, and asks before writing. A shell target prints deterministic network-free source.\",\"flags\": \"yes\",\"dry-run\",\"color\",\"help\" ,\"examples\":  \"command\":\"lingua completion\",\"description\":\"Detect supported shells and offer to install their completions.\" , \"command\":\"lingua completion install --yes\",\"description\":\"Install every detected completion without prompting.\"    ,\"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\":\"yes\",\"syntax\":\"--yes\",\"summary\":\"Approve detected shell-completion changes without prompting.\",\"commands\": \"completion\"  , \"id\":\"dry-run\",\"syntax\":\"--dry-run\",\"summary\":\"Show detected shells and target files without writing.\",\"commands\": \"completion\"  , \"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

Install the CLI with Homebrew on macOS, use @linguacode/cli through npm or npx, or build it from source. Pin a version for automation.

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.