escli

escli is the Eightstate command line for agent-friendly AI workflows: auth, models, usage, docs, fetch, search, social search, audio transcription, and image generation/editing.

Version 0.5.0 is the TypeScript/Bun cutover. The CLI now ships as native binaries and uses the stable {ok,data,error,meta} JSON envelope.

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/eight-state/eightstate/main/cli/install.sh | bash

Set ESCLI_VERSION, ESCLI_RELEASE_BASE_URL, or ESCLI_INSTALL_DIR to override the release or install location. Default install dir: $HOME/.local/bin.

Windows PowerShell

irm https://raw.githubusercontent.com/eight-state/eightstate/main/cli/install.ps1 | iex

Default install dir: $env:LOCALAPPDATA\eightstate\bin.

npm

pnpm add -g @eightstate/escli
# or npm install -g @eightstate/escli

The native archive installers are the primary zero-runtime path. npm is supported for JS environments.

Quickstart

escli auth login
escli models
escli docs get react "useEffect cleanup" --tokens 5000
escli search "Cloudflare Workers 2026 limits"
escli fetch https://example.com --objective "pricing"
escli audio transcribe meeting.mp3 --speakers
escli image generate "a sunset over the ocean" --open

Short aliases include i g/i e, a s, d g, au t, m, s, f, and u.

JSON envelope

Use --json --quiet for automation. stdout is exactly one JSON object plus a trailing newline.

Success:

{"ok":true,"data":{},"error":null,"meta":{"schema_version":"1","escli_version":"0.5.0","command":"version","warnings":[]}}

Failure:

{"ok":false,"data":null,"error":{"code":"auth.required","message":"not authenticated","remediation":{"command":"escli auth login"}},"meta":{"schema_version":"1","escli_version":"0.5.0","command":"models","warnings":[]}}

This replaces the pre-0.5 {success,...} shape.

Exit codes

| Code | Meaning | |---:|---| | 0 | success | | 1 | non-retryable service/client error | | 2 | usage, parsing, validation, missing argument | | 4 | auth or permission failure | | 5 | not found | | 8 | transient/retryable network, rate-limit, timeout, or service-unavailable failure |

Manifest and schema

escli --describe                 # compact full manifest
escli --schema                   # full manifest with schemas
escli --schema docs              # docs namespace only
escli --schema docs get          # docs get leaf only

Manifest output is contract-validated and includes command ids, aliases, args, flags, examples, error codes, input schemas, and output envelope schemas.

Command shape

Commands use noun verb [args] [options]. Root leaves (models, search, fetch, social, usage, version) remain single-token. Namespaced topics (auth, audio, docs, image) print a usage envelope and exit 2 when called without a verb.

Environment

Common variables:

| Variable | Description | |---|---| | ESCLI_API_KEY | API key override | | ESCLI_BASE_URL | OpenAI-compatible endpoint override | | ESCLI_GATE_URL | Eightstate gate endpoint override | | ESCLI_CONFIG_DIR | config directory, default ~/.escli | | ESCLI_CACHE_DIR | cache directory | | service keys | OPENAI_API_KEY, PARALLEL_API_KEY, ASSEMBLYAI_API_KEY, TAVILY_API_KEY, CONTEXT7_API_KEY |

Credentials are stored in config.json under ESCLI_CONFIG_DIR with owner-only permissions where supported.