Prompsit CLI

One CLI for the entire Prompsit Translation API. Translate text and documents, evaluate translation quality, score parallel corpora with Bicleaner-AI, and annotate monolingual data with Monotextor — from your terminal or an interactive REPL.

Quick Start

npm install -g prompsit-cli

prompsit login
prompsit health
prompsit translate "Hello world" -s "en" -t "es"
prompsit translate @"report.docx" -s "en" -t "es"
prompsit                                            # Interactive REPL

Tip

Run prompsit with no arguments to enter the interactive REPL with tab completion, command history, and bundled example files in ~/.prompsit/examples/.

Important

Requires Node.js 22.19+. On Linux, use a Node version manager such as nvm or configure npm to use a user-owned prefix; do not use sudo npm install -g.

Update: npm install -g prompsit-cli@latest Uninstall: npm uninstall -g prompsit-cli Occasional use: npx prompsit-cli --help

---

Features

Feature	Description	Example
Translate text	Translate one or more segments with optional quality estimation	translate "Hello" -s "en" -t "es" --qe
Translate files	Translate documents with SSE progress tracking	translate @"report.pdf" -s "en" -t "es"
Evaluate	Measure translation quality (BLEU, chrF, MetricX, COMET)	eval -s "Hello" -h "Hola" -r "Hola"
Score	Score parallel corpora with Bicleaner-AI	score @"corpus.tmx"
Annotate	Add metadata to monolingual data (LID, PII, dedup, etc.)	annotate @"data.jsonl" -l "en"
Engines	List available translation engines by language pair	engines -s "en" -t "es"

Supports XLIFF, CSV, PDF, DOCX, TMX, TSV, TXT, JSONL, and more. Run prompsit translate --formats for the full list.

---

Commands

Important

Quoting rule: all values must be quoted. Commands, subcommands, and flags stay unquoted. Run prompsit <command> --help for the full flag reference.

Authentication

prompsit login                           # Sign in or register with Google
prompsit login -a "EMAIL" -s "SECRET"    # Fallback for issued API secrets
prompsit logout                          # Clear stored credentials
prompsit status                          # Show auth state and token expiry

Translation

# Text mode
prompsit translate "Hello world" -s "en" -t "es"
prompsit translate "Hello" "Good morning" -s "en" -t "es" --qe

# File mode (@ prefix)
prompsit translate @"report.pdf" -s "en" -t "es" --output-format "docx"
prompsit translate @"file1.csv" @"file2.csv" -s "en" -t "es" --out "./translated/"

# Discovery
prompsit translate --languages -s "en"
prompsit translate --formats

Evaluation

prompsit eval -s "Hello" -h "Hola" -r "Hola"                    # Inline
prompsit eval -s "Hello" -h "Hola" -r "Hola" -m "bleu,metricx"  # Custom metrics
prompsit eval "segments.tsv" -m "bleu,chrf"                      # Batch from TSV
prompsit eval @"report.txt" -s "en" -t "es"                      # File scoring

Tag quality (reference-free, no -r): checks that inline tags/placeholders are preserved and correctly positioned. Sub-scores default to both; restrict with -m.

prompsit eval -s "Hello <b>world</b>" -h "Hola <b>mundo</b>" --tags                       # Inline
prompsit eval -s "Hello <b>world</b>" -h "Hola <b>mundo</b>" --tags -m "tag_preservation"  # One sub-score
prompsit eval "pairs.tsv" --tags                                                          # Batch: 2-column TSV (source<TAB>hypothesis)

Data Processing

prompsit score @"corpus.tmx"                                                    # Bicleaner-AI scoring
prompsit score "corpus.tsv" --output-format "tsv" --out "results/"

prompsit annotate @"data.jsonl" -l "en" --metadata "lid,docscorer"              # Monotextor annotation
prompsit annotate @"data.jsonl" -l "en" --out "results/"
prompsit annotate --metadata                                                    # List available metadata

Configuration

prompsit config                          # Open interactive TUI settings screen
prompsit config show                     # Show current configuration
prompsit config "api-base-url"           # Get a value
prompsit config "api-base-url" "URL"     # Set a value
prompsit config api-url "test"           # Switch API endpoint preset
prompsit language "es"                   # Set interface language

System

Command	Description
health	API health check
usage	Show plan usage and quotas
help	Show all commands (also: ?)
clear	Clear screen
exit	Quit REPL (also: quit, q)

---

FAQ

How do I get access?

Run prompsit login without arguments. The CLI starts the Google device-flow sign-in, prints a one-time code and URL, tries to open the browser, and copies the sign-in URL to the clipboard when possible. On first registration, the API can return a Prompsit secret; the CLI stores it in ~/.prompsit/credentials.json and prints a fallback login -a ... -s ... command.

Linux install fails with EACCES?

This is usually an npm prefix permissions issue, not a Prompsit CLI issue. The preferred fix is to install Node.js 22.19+ with a version manager such as nvm, fnm, or Volta. If you use system Node/npm, configure a user-owned npm prefix:

mkdir -p ~/.local
npm config set prefix ~/.local
echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.profile
source ~/.profile
npm install -g prompsit-cli

REPL or CLI — which should I use?

REPL (prompsit with no args) — for interactive exploration. Tab completion, persistent command history, bundled examples in ~/.prompsit/examples/, and a settings TUI (config).

CLI (prompsit <command>) — for scripts, pipelines, and one-off commands. Same commands, same flags.

What file formats are supported?

XLIFF, CSV, PDF, DOCX, TMX, TSV, TXT, JSONL, and others. Run prompsit translate --formats for the complete list. Use --output-format to convert between formats (e.g., PDF to DOCX).

How does configuration work?

Three-level precedence: environment variables (PROMPSIT_API__BASE_URL) > config file (~/.prompsit/config.toml) > defaults. Use config show to see active values. See runbook for details.

How do I change the interface language?

prompsit language "es"     # CLI
> language "es"            # REPL

Translations are fetched from the API on first use and cached in ~/.prompsit/translations/.

Command not found after install?

# Check global npm bin is on PATH
NPM_PREFIX="$(npm prefix -g)"
echo "$NPM_PREFIX/bin"
echo "$PATH" | tr ':' '\n' | grep -E '(\.local|node_modules)/bin'
command -v prompsit

Something is broken — where do I start?

1. prompsit health — verify API connectivity
2. prompsit status — check authentication state
3. prompsit config show — review active configuration
4. See the runbook for common errors and fixes

---

Project Structure

src/
├── index.ts              # Entry point
├── program.ts            # Commander.js program definition
├── commands/             # CLI command handlers
├── api/                  # HTTP client (got) + Zod models + SSE
├── config/               # Settings (Zod + smol-toml + env vars)
├── repl/                 # Interactive REPL (pi-tui)
├── tui/                  # TUI settings screen
├── output/               # Terminal formatting (chalk + cli-table3)
├── i18n/                 # Internationalization
├── errors/               # Error contracts
├── cli/                  # Global options, exit codes
├── runtime/              # Platform abstractions
└── logging/              # Telemetry transport

Tip

For AI agents: entry point is src/index.ts -> src/program.ts. Commands in src/commands/, REPL in src/repl/, config in src/config/. TypeScript strict, ESM-only, layered architecture (Presentation -> Application -> Domain -> Infrastructure). Full docs: architecture.md, CLAUDE.md.

---

Links

Documentation	docs/README.md
Architecture	docs/project/architecture.md
Runbook	docs/project/runbook.md
Contributing	CONTRIBUTING.md
Issues	GitHub Issues
npm	prompsit-cli

License

Apache-2.0 — Prompsit Language Engineering, S.L.