Skip to content
tansr 资料站

CLI in 5 minutes

tansr is the developer-facing agent CLI: one kernel offered in five forms — interactive terminal (TUI), headless scripts, a long-running service (serve), an editor agent (acp) and an MCP tool service (mcp serve). This article takes the shortest path only: install, sign in, say one thing, glance at the event stream.

Prerequisites

Section titled “Prerequisites”
  • Node.js ≥ 22.19 (npm package form). The single-file executable (SEA) bundles its own Node runtime, nothing to preinstall.
  • Windows / macOS / Linux are all supported. On Windows, Windows Terminal is recommended; the legacy conhost automatically switches to the ASCII glyph set, with no loss of functionality.

Install

Section titled “Install”

npm form (recommended):

终端窗口
npm i -g @tansr/cli
tansr --version

The package is @tansr/cli; the command is tansr.

Single-file form: download the executable for your platform from the official distribution point (named like tansr-sea-win32-x64.exe), verify it against SHA256SUMS, and put it on your PATH:

https://bash.tansr.com/release/stable/tansr-sea-win32-x64.exe
https://bash.tansr.com/release/stable/SHA256SUMS

Credentials: sign in with a personal access token

Section titled “Credentials: sign in with a personal access token”

The CLI runs in platform mode: once signed in, the model list and price list are pushed by the platform; you never hand-write provider config.

  1. Create a personal access token (PAT) in the console.
  2. Run the init wizard and paste the PAT when prompted (masked input, not echoed):
终端窗口
tansr init

The wizard verifies your identity, derives an app credential for this machine, writes it to the OS keychain (falling back to a file with mode 0600 and telling you so when the keychain is unavailable), and finally shows a summary card: account fingerprint, balance, recent usage, number of available models, derived-key expiry. The whole process makes zero model calls and can be repeated.

Non-interactive, for scripts or CI:

终端窗口
TANSR_PAT=<PAT> tansr init

Note that tansr init --pat <PAT> also works, but leaves the value in your shell history and is not recommended.

Sign out with tansr logout: it clears the local credential and does its best to deactivate this machine’s derived key; your PAT itself is not revoked (other devices may still be using it).

First session

Section titled “First session”

Run tansr on its own to enter the interactive terminal:

终端窗口
tansr

It opens with a welcome banner and a “basic configuration summary” (signed-in identity, portal address, current model, context scheme and balance). Type in the input area and press Enter to chat; @ references workspace files, / opens slash commands. A few commands you will use on day one:

Command Purpose
/help List all commands
/status Version / language / session / model
/model Open the model picker, or /model <alias> to switch directly
/cost /usage Cost and token usage of this session
/doctor Assembly self-check
/quit Exit

Esc interrupts the current turn, Ctrl+T opens the full-screen transcript view, Ctrl+C also interrupts.

See the events

Section titled “See the events”

In headless mode everything is an event. Give -p a prompt and add --json, and you get an NDJSON event stream — one JSON object per line — always ending with a type: "result" summary:

终端窗口
tansr -p "用一句话介绍这个目录" --json
{"type":"result","reason":"completed","exitCode":0,"usage":{"inputTokens":1200,"outputTokens":300}}

The event envelope fields are type / sessionId / seq / ts / v / source; the main event families are session.*, turn.*, msg.*, tool.*, agent.*, hook.*, cost.*, mcp.*, plan.*. Exit codes: 0 success, 1 model or internal error, 2 interrupted, 3 limit reached (turns / budget), 4 prompt too long, 5 usage error.

Consuming the stream from Node takes a few lines:

import { createInterface } from 'node:readline';
import { spawn } from 'node:child_process';


const child = spawn('tansr', ['-p', '总结本仓库', '--json'], { stdio: ['ignore', 'pipe', 'inherit'] });
for await (const line of createInterface({ input: child.stdout })) {
  const ev = JSON.parse(line);
  if (ev.type === 'msg.text.delta') process.stdout.write(ev.text);
  if (ev.type === 'result') console.log('\n退出码:', ev.exitCode, '原因:', ev.reason);
}

Headless mode has no prompt channel: whenever a permission decision lands on “ask”, it degrades to deny (fail-closed). To grant, use session-level rules like --allowedTools "Shell(git *),Read", or --permission-mode to set the initial mode.

Common first hurdles

Section titled “Common first hurdles”
Symptom Fix
“The TUI needs an interactive terminal (TTY)” You started tansr inside a pipe; use -p for non-interactive runs
Started without initializing You land on an empty-state onboarding card; type /init there to sign in. Unattended forms exit with code 5 and point you to tansr init
Balance is zero The summary card warns but does not block; platform model calls are rejected by the server-side billing gate, local features are unaffected
I do not want the platform at all Set TANSR_ESCAPE_LOCAL=1 and configure a local provider in .tansr/settings.json as described in the user manual

Next steps

Section titled “Next steps”