Metadata-Version: 2.4
Name: eightstatecli
Version: 0.4.1
Summary: Eightstate CLI — unified AI services from the command line
Project-URL: Homepage, https://github.com/eight-state/eightstate
Project-URL: Repository, https://github.com/eight-state/eightstate
Author-email: Eightstate <hello@eightstate.co>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,cli,image-generation,research,transcription,web-search
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24.0
Requires-Dist: openai>=1.0.0
Description-Content-Type: text/markdown

# 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

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

### Windows

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

### Manual install (any platform)

```bash
# 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

```bash
# 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

```bash
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

```bash
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

```bash
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:

```bash
# 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
