CLI Reference

The witan CLI provides document reading, spreadsheet automation, workbook verification, and authentication commands.

Installation

macOS and Linux

curl -fsSL https://witanlabs.com/install.sh | sh

The install script downloads the latest release artifact, verifies its checksum, and installs witan to /usr/local/bin by default.

PyPI

# Zero-install one-shot
uvx witan xlsx render report.xlsx -r "Sheet1!A1:Z50"

# Persistent install
pip install witan

npm

# Zero-install one-shot
npx witan xlsx render report.xlsx -r "Sheet1!A1:Z50"

# Persistent install
npm install witan

The npm package requires Node.js 22 or later.

Manual Download

Use the latest GitHub release artifacts:

curl -fsSL https://github.com/witanlabs/witan-cli/releases/latest/download/witan-darwin-arm64.tar.gz | tar -xz
install -m 0755 witan /usr/local/bin/witan

Replace witan-darwin-arm64.tar.gz with the artifact for your platform. https://witanlabs.com/dl/<artifact> URLs are aliases for the same files.

Global Options

witan [flags] <command>

Transport mode is credential-dependent. Without credentials, the CLI uses stateless mode: each command sends workbook bytes and does not reuse a server-side file cache. With credentials, the CLI uses files-backed mode by default: it uploads workbook revisions and reuses them across commands. Pass --stateless or set WITAN_STATELESS=1 / true to force stateless mode even when credentials are available.

Workbook inputs must be 25 MB or smaller.

Authentication and Environment

The personal tier does not require an API key. For organization-backed requests, either sign in with witan auth login or pass an API key from app.witanlabs.com/~/settings/api-keys.

export WITAN_API_KEY="sk_..."

On Windows PowerShell:

$env:WITAN_API_KEY = "sk_..."

Environment variables:

Zero Data Retention

Stateless mode is active automatically when no credentials are available, and can be forced with WITAN_STATELESS=1 or --stateless. In stateless mode, each command sends file bytes for that request and does not reuse a server-side file cache:

export WITAN_STATELESS=1
witan xlsx render confidential-report.xlsx -r "Sheet1!A1:Z50"

The trade-off is that each command re-uploads the file. Repeated operations are slower than authenticated files-backed mode, but the command avoids server-side file caching.

Commands

witan auth

Manage local credentials for organization-backed requests.

witan auth login
witan auth status
witan auth status --json
witan auth logout

witan auth login

Starts browser-based device-code sign-in, exchanges the device code for a session token, asks for an organization if more than one is available, and saves the session locally.

For non-interactive environments, use --api-key or WITAN_API_KEY.

witan auth status

Shows the active credential source, validation status, active organization when known, and ignored lower-priority credentials.

witan auth logout

Attempts to revoke the current server session, then removes locally saved session credentials. If no session exists, it exits successfully.

witan read

Extract text content or document outlines from source material.

witan read <file-or-url> [flags]

Supported inputs include local files and HTTP(S) URLs.

Examples:

witan read report.pdf --outline
witan read report.pdf --pages 1-5
witan read slides.pptx --slides 1-3
witan read notes.docx --offset 50 --limit 100
witan read https://example.com/report.pdf --outline
witan read data.csv --json

witan xlsx

Spreadsheet commands operate on .xls, .xlsx, and .xlsm workbooks. The CLI automatically corrects mismatched .xls/.xlsx extensions when file bytes reveal the other Excel format.

witan xlsx [--json] <command>

witan xlsx exec

Execute JavaScript against a workbook. The CLI Scripting page covers the scripting surface; this section is the command shape.

witan xlsx exec <file> [flags]

Provide exactly one code source: --code, --script, --stdin, or --expr.

Exit codes:

witan xlsx rpc

Run newline-delimited xlsx RPC over stdio. Use this for persistent low-latency workbook sessions and SDK integrations.

witan xlsx rpc <file> [flags]

The CLI opens the workbook session. Input lines should not include a workbook field.

{"id":"1","op":"listSheets","args":{}}
{"id":"2","op":"readRange","args":{"address":"Sheet1!A1:B10"}}
{"id":"3","op":"save","args":{}}

Stdout contains one redacted JSON response per request. Stderr is reserved for CLI diagnostics.

witan xlsx calc

Recalculate formulas and update cached values, or run non-mutating verification with --verify.

witan xlsx calc <file> [flags]

Exit codes:

witan xlsx lint

Run semantic formula and layout checks.

witan xlsx lint <file> [flags]

Exit codes:

witan xlsx render

Render a sheet-qualified range as a PNG or WebP image.

witan xlsx render <file> [flags]

Every invocation prints the output image path and render metadata. Large images may be downscaled by vision models; reduce the range or DPR when the output exceeds 1568 px on either axis.

Supported Workbook Formats

• .xlsx (Office Open XML)
• .xls (Excel 97-2003)
• .xlsm (macro-enabled; macros are preserved but not executed)

Related Pages

• CLI Scripting — agent scripting surface.
• Workbook API — full xlsx.* method signatures and return shapes.