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

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.

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 (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.

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).

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.

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

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

# 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

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.