TeXRA CLI

The TeXRA CLI provides a local texra command for running TeXRA agents from a terminal. It is published to npm as @texra-ai/cli.

Install

Install the CLI globally from npm (requires Node.js >=22.9.0):

npm install -g @texra-ai/cli

Or with Homebrew on macOS and Linux, which installs Node.js for you if needed:

brew install texra-ai/tap/texra

Verify the command:

texra --help
texra version
texra agents list

Running Agents

Run a workflow agent from a project directory:

texra run polish --input paper.tex --output paper.polished.tex --print

texra run

$texra run polish --input paper.tex --output paper.polished.tex --print

• r0 — draft revision
• r1 — critique and revise

paper.polished.tex

Command in, rounds stream as progress, and the printed path is the success signal: the copied --output destination, or the generated file in run storage when no copy was requested.

Pass read-only context files with repeated --context flags. The agent can read these files through {{ ALL_CONTEXTS }}, but it should only emit revised documents for the selected inputs:

texra run correct --input appendices.tex --context Draft0.tex --context refs.bib

Pass multiple inputs with repeated --input flags, a directory, or a glob. Directory inputs expand recursively to .tex files. Multi-input runs can copy their generated artifacts to a directory with --output-dir; relative document paths are preserved under that directory:

texra run polish --input Draft0.tex --input appendices.tex --output-dir polished
texra run correct --input 'paper/**/*.tex' --output-dir corrected

Workflow agents always write generated files into the execution's run-storage directory first. In text mode, TeXRA prints a filesystem path: the copied path when --output or --output-dir is used, otherwise the final generated file in run storage.

With --output, TeXRA also copies the final artifact to the requested filesystem destination. JSON and NDJSON output keep outputs[] as the run-storage source of truth (relativePath, absolutePath, and location), include runDirectory, include copiedOutput or copiedOutputs when a filesystem copy was written, and report terminalStatus for the completed run.

Authentication

You can run the CLI either with a TeXRA sign-in (included hosted access) or with your own provider API keys — whichever you prefer.

Includedhosted

you@github

texra login

Sign in with GitHub or Google.

No keys to manage

Personal keysBYOK

• ANTHROPIC_API_KEY=sk-…
• OPENAI_API_KEY
• GOOGLE_API_KEY

Set the provider env var, then run as usual.

No sign-in needed

Per-run override--api-mode personaluses your key even while signed indirectapibyokvsincluded

Two credential paths: included hosted access after texra login, or your own provider keys via env vars. --api-mode personal flips a single run to your key even while signed in.

Sign in with GitHub or Google to use included access without managing keys:

texra login                 # pick GitHub or Google, then sign in via browser
texra login github          # choose the OAuth provider explicitly
texra login --no-browser    # print the loopback sign-in URL
texra login --device        # device code: approve from a browser on any device

When run interactively, a bare texra login asks which provider to use instead of silently defaulting. If you juggle multiple accounts, --select-account forces the OAuth account chooser and --login-hint <email> suggests which account to use.

--no-browser still uses a local callback server. Open the printed URL in a browser that can reach the terminal session; SSH and container sessions may need callback port forwarding.

--device needs no callback at all: the CLI prints a short code and a verification URL, you open the URL in a browser on any device (your laptop, even your phone), sign in, and approve the code. This is the recommended path on SSH, WSL2, and containers — the interactive pickers offer it automatically when they detect a remote session.

texra auth                  # same as `texra auth status`
texra auth status           # who am I signed in as?
texra auth usage            # how much of my included quota have I used?
texra logout

texra auth on its own reports your account status and accepts the same flags as texra auth status, such as --output-format json.

CI pipelines. Headless pipelines can't sign in interactively. Mint a long-lived relay token once, store it as a CI secret, and set TEXRA_RELAY_TOKEN in the pipeline environment:

texra setup-token --name "release pipeline" --expires 90
texra setup-token --print-env >> "$GITHUB_ENV"   # GitHub Actions: env line only
texra auth token list                            # audit your tokens
texra auth token revoke <id>                     # rotate / kill a leaked token

CI tokens are scoped to relay model calls only — they cannot manage your account or mint more tokens. They default to a 30-day expiry (cap 365), are stored server-side only as hashes (the plaintext is shown exactly once at mint time), and their usage counts toward the same monthly relay quota as your interactive use. With TEXRA_RELAY_TOKEN set, texra run … needs no other credentials.

Bring your own provider keys. Set the right environment variable for the provider you want to use (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, …), then run the CLI normally:

export ANTHROPIC_API_KEY=sk-…
texra run polish --input paper.tex

If you're signed in and want this particular run to use your own key instead of hosted access, add --api-mode personal.

The CLI doesn't read .env files automatically. If you already keep keys there, load them into the shell first (in bash/zsh: set -a; . .env; set +a).

Run texra doctor any time to see which dependencies are detected, who you're signed in as, and which models the CLI can reach with the current credentials.

Interactive Chat

texra chat opens an interactive tool-use session in the terminal. It streams reasoning, tool calls, and diffs, and writes to the same run history as the VS Code extension.

texra chat

$texra chat --agent research

{ T } TeXRAv0.38.8relay

agent: research · model: deepseekT

›Polish the introduction and fix the awkward opener.

Reading the section, then tightening the opener.

• ●read_file(sections/intro.tex)
  ⎿In this paper we present a novel approach to
  … +41 lines (ctrl + t to view transcript)
• ●edit_file(sections/intro.tex)

⎿sections/intro.tex

-In this paper we present a novel approach to

+We introduce

◆running8srelayr112.3k/1M (1%)[/model]models [/api]api [Ctrl-C]stop

A texra chat session streams reasoning and tool calls inline, shows diffs as the agent edits, and lists its slash commands at the bottom.

texra chat                          # default chat agent and model
texra chat --agent research         # pick a tool-use agent for the session
texra chat --model deepseekT        # override the session model
# headless tool-use run for scripts and CI
texra agents run review --input main.tex --instruction "Check the proof." --print

Slash commands inside the session: /tools lists and toggles integrations, /api switches between hosted and personal-key access, /model switches to another model from the same provider mid-session (the change applies immediately and persists on resume), /skills lists available skills and applies one to your next request, and /resume restores a stored execution. Chat requires an interactive terminal — for scripted, non-TTY runs use texra agents run <agent> with --print or --output-format json|ndjson. It accepts workspace --input and --context files plus an --instruction prompt for the tool-use agent. Use texra run for workflow agents that take input files and produce document-oriented outputs.

Multi-Agent Teams

The CLI can list, show, and run the same built-in teams as the extension's Multi-Agent settings tab — Lean Project, Physicist, Mathematician, Computer Scientist, and Software Engineer:

texra multi-agent list
texra multi-agent show software-engineer
texra multi-agent run software-engineer --instruction "Profile and speed up scripts/simulate.py"

run starts the team's orchestrator, which plans the work and delegates to its specialists. For example, the Software Engineer team's engineer lead delegates to coder, codeReviewer, testEngineer, codeSimplifier, and progressCheck. Pass --input and --context files as with texra run; read-only context files are included in the instruction the team receives.

texra multi-agent

$texra multi-agent run software-engineer --instruction "Profile and speed up scripts/simulate.py"

engineerrunning1m 12s

• 1●codercompleted48s
  optimized the inner loop in scripts/simulate.py
• 2●testEngineerrunning21s
  pytest -q · 17 passed, 3 to go

[Tab]streams [Esc 1..9]focus [Esc s]subagentseach subagent keeps its own transcript

The lead delegates while child agents stream below it as numbered subagent rows — each one a focusable stream with its own scoped transcript.

In an interactive team session, focusing a subagent shows only its own transcript — scroll back through its earlier output with normal terminal scrolling and search. Each subagent keeps its own scoped history that persists across sessions, and resuming a subagent continues it where it left off.

Skills

Skills are reusable instruction folders the agent can apply to a request. List what's available, and pull in extra skill folders for any agent run:

texra skills list
texra run polish --input paper.tex --source ~/my-skills
texra chat --include-interop

--source (alias -s) adds an additional skill root and may be repeated; --include-interop also includes .agents, .claude, .codex, and .gemini skill folders from the workspace and home directory. When skills share a name, project and user skills take precedence over bundled ones. In chat, pick a skill with /skills to apply it to your next request.

Shell Completion

TeXRA can print completion scripts for Bash, Zsh, and Fish:

texra completion bash >> ~/.bashrc
texra completion zsh > "${fpath[1]}/_texra"
texra completion fish > ~/.config/fish/completions/texra.fish

Restart the shell, or source the file you updated. Completion includes subcommands, flags, enum values such as --output-format text|json|ndjson, agent names for texra run <TAB>, and model names for --model <TAB>.

Agent and model completion call back into texra agents list and texra models list. Disable those dynamic lookups in slow shells with:

export TEXRA_COMPLETION_DYNAMIC=0

Execution History

TeXRA stores completed executions in the workspace run store. List recent runs:

texra history list
texra history list --limit 10        # only the most recent runs (alias: -n)
texra history list --output-format ndjson

Text output prints one tab-separated row per execution:

<id>    <timestamp>    <agent>    <status>    <primary input>

The NDJSON form is stable for scripts. Each line has kind history-entry and contains the same execution entry object used by JSON output.

Inspect or delete one execution:

texra history show <id>
texra history delete <id>

Reopen a stored tool-use session in the interactive chat, on the saved agent and model:

texra resume <id>
texra --resume <id>

Resume is interactive-only — a resumed session waits for your next message, so without a terminal it exits with a usage error that points scripting at texra run. The interactive chat also accepts /resume: with no id it prints recent executions, with an id it continues the stored session. A missing or malformed id exits with code 2.

Tools and Integrations

The CLI can inspect the same external agent integrations shown in the extension settings:

texra tools list
texra tools status codex
texra tools disable codex
texra tools enable codex
texra tools install codex
texra tools auth codex

tools list reports each integration id, name, category, enabled state, and detection result.

texra tools list

$texra tools list

IDNAMECATEGORYENABLEDDETECTEDNOTE

codexOpenAI Codex CLIai-agents yes yesUses ChatGPT subscription (free with Plus/Pro)

claude-agentClaude Code CLIai-agents yes nonpm install -g @anthropic-ai/claude-code

zoteroZotero Integrationai-agents no yesZotero must be running with Better BibTeX installed. Port configurable via texra.bib.zoteroPort.

wolframWolfram Languagecomputation - noRequires the free Wolfram Engine (provides wolframscript).

lean4Lean 4 Proof Assistantlean - yesVS Code build: requires the leanprover.lean4 extension. CLI / desktop builds: requires `lake` on PATH; each Lake project root gets its own language server, surfaced below.

tools list reports six columns per integration: a status dot marks the enabled state, a check or cross marks whether the backing tool was detected on this machine, and the note carries the registered install command when something is missing.

Use --output-format json or --output-format ndjson for scripts. tools install <id> prints the install guide and registered command; it only runs the command when passed --run. In the interactive TUI, /tools opens the same integration list and toggles integrations that support enabling or disabling.

Workspace Defaults

The CLI reads optional, non-secret defaults from .texra/config.json in the current workspace. Scaffold one with texra init (add --yes to accept defaults non-interactively, or --gitignore to add .texra/ to .gitignore). Command-line flags override environment variables, environment variables override the workspace file, and the workspace file overrides built-in defaults.

overrides ↓

• 1
  CLI flagshighest priority

  --model deepseekTwins
• 2
  Environment variablesshell exports

  TEXRA_MODELTEXRA_AGENTTEXRA_OUTPUT_FORMATTEXRA_APPROVAL_POLICYTEXRA_API_MODE
• 3
  Workspace file.texra/config.json

  "model": …
• 4
  Built-in defaultlowest priority

  deepseekT

Resolution order, highest priority on top: a CLI flag beats its TEXRA_* env var, which beats the .texra/config.json key, which beats the built-in default (deepseekT).

{
  "model": "deepseekT",
  "outputFormat": "text",
  "approvalPolicy": "never",
  "chat": {
    "agent": "assistant",
    "model": "deepseekT"
  },
  "run": {
    "model": "deepseekT"
  }
}

Supported top-level keys are agent, model, outputFormat, and approvalPolicy; chat and run may set command-specific agent and model defaults. The built-in CLI model default is deepseekT.

The corresponding environment variables are TEXRA_AGENT, TEXRA_MODEL, TEXRA_OUTPUT_FORMAT, TEXRA_APPROVAL_POLICY, and TEXRA_API_MODE. Run texra doctor to see which workspace config file was loaded and whether any keys were ignored.

Use --api-mode personal or TEXRA_API_MODE=personal to force a run or chat invocation to use provider API keys even when the CLI is signed in for included hosted access. --api-mode included keeps the default hosted behavior when the account is signed in. The accepted aliases match the TUI /api command: for example, direct, api, and byok select personal API keys, while included selects hosted access.