eightstatecli 0.4.0

Eightstate CLI — unified AI services from the command line

escli

  ┌─────────────────────────────────┐
  │  escli                  v0.3.1  │
  │  eightstate command line        │
  └─────────────────────────────────┘

AI services from the command line. Generate images, edit photos, and more. Works for humans and agents.

Install

macOS / Linux

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

Windows

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

Manual install (any platform)

# requires uv (https://docs.astral.sh/uv)
uv tool install git+https://github.com/eight-state/eightstate#subdirectory=cli

# or with pip
pip install git+https://github.com/eight-state/eightstate#subdirectory=cli

Quickstart

# 1. authenticate
escli auth login

# 2. generate an image
escli image gen "a sunset over the ocean" --open

# 3. list models
escli models

Usage

Image Generation

escli i g "a mountain landscape"                    # square, auto-named
escli i g "app mockup" -s portrait -q high --open   # portrait, opens after
escli i g "logo design" -s sq -o logo.png           # named output
escli i g "wallpaper" -s wide -f webp               # landscape webp
escli i g "product photo" -q high -d ./output/      # to directory

Image Editing

escli i e "make it snow" -i summer.jpg --open
escli i e "repaint as oil painting" -i photo.jpg -q high -o painted.png
escli i e "remove the background" -i product.png

Sizes

Alias	Dimensions	Use case
square, sq	1024x1024	Logos, icons, social posts
landscape, wide, ls	1536x1024	Wallpapers, banners, headers
portrait, tall, port	1024x1536	Phone mockups, posters, stories

Quality

Level	Speed	Detail
low	~15s	Fast drafts
medium	~25s	Balanced
high	~40s	Best quality

Auth Profiles

escli auth login                        # interactive
escli auth login --key sk-xxx           # non-interactive
escli auth login --key sk-xxx -p work   # named profile
escli auth status                       # show current (alias: whoami)
escli auth profiles                     # list all (alias: ls)
escli auth switch work                  # switch profile (alias: use)
escli auth logout                       # remove current
escli auth logout --all                 # remove everything

Agent / CI Usage

All commands support --json for structured output and --quiet for zero stderr noise:

# generate with pure JSON output
escli --json --quiet i g "a logo" -s sq -o /tmp/logo.png

# returns:
# {"success": true, "path": "/abs/path/logo.png", "size_bytes": 123456,
#  "elapsed_seconds": 18.4, "prompt": "a logo", "model": "gpt-image-2",
#  "image_size": "1024x1024", "quality": "high"}

# auth via env var (no login needed)
ESCLI_API_KEY=sk-xxx escli --json models

# non-interactive login for CI
escli auth login --key $API_KEY --profile ci

# edit with JSON output
escli --json --quiet i e "make it blue" -i input.png -o output.png
# {"success": true, "path": "/abs/path/output.png", "input": "/abs/path/input.png", ...}

Exit codes: 0 success, 1 error, 2 usage

Error JSON: {"success": false, "error": "message"}

Shortcuts

Short	Full
escli i g	escli image generate
escli i e	escli image edit
escli a	escli auth
escli m	escli models

Environment Variables

Variable	Description	Default
ESCLI_API_KEY	API key (overrides profile)
ESCLI_BASE_URL	API endpoint	https://ai.eightstate.co/v1
ESCLI_IMAGE_MODEL	Default model	gpt-image-2
ESCLI_IMAGE_QUALITY	Default quality	high
ESCLI_IMAGE_SIZE	Default size	1024x1024
ESCLI_IMAGE_FORMAT	Default format	png
ESCLI_OUT_DIR	Output directory	.
ESCLI_TIMEOUT	Timeout seconds	300
ESCLI_CONFIG_DIR	Config directory	~/.escli

Config

Credentials stored at ~/.escli/config.json with 600 permissions (owner-only read/write).

License

MIT