AI Chaos CLI

AI Chaos CLI

aichaos is a thin command-line client for the AI Chaos public API. It talks to the same endpoints as the web app and the Telegram bot — OpenAI-compatible chat, image generation, status polling, download, and model listing — using only the Ruby standard library.

Requirements

  • Ruby 3.1+ (developed and tested on Ruby 4.0). No gems, no Bundler, no Rails.

Installation

The CLI lives in the repository at cli/ and runs directly from the checkout:

```bash # From the repository root ./cli/bin/aichaos –help

Or with plain ruby (no executable bit needed)

ruby cli/bin/aichaos –version ```

To use it anywhere, add a symlink on your PATH:

bash ln -s "$(pwd)/cli/bin/aichaos" ~/.local/bin/aichaos aichaos --version # aichaos 0.1.0

There is no package installation; the binary is a single self-contained script backed by cli/lib/aichaos.rb.

Configuration

The API key and base URL are resolved from (highest precedence first):

  1. Command-line flags --api-key KEY / --base-url URL
  2. Environment variables AICHAOS_API_KEY / AICHAOS_BASE_URL
  3. A JSON config file AICHAOS_CONFIG or ~/.config/aichaos/config.json
  4. Default base URL https://aichaos.ru

```bash export AICHAOS_API_KEY=”sk-…”

Optional config file (~/.config/aichaos/config.json)

cat > ~/.config/aichaos/config.json «‘JSON’ { “api_key”: “sk-…”, “base_url”: “https://aichaos.ru” } JSON ```

Create a key in Settings → API keys on the site. Public metadata endpoints (models) work without a key; every other command requires one.

Commands

models — list published models

bash aichaos models # all models aichaos models --purpose chat # chat models only aichaos models --json # machine-readable

Reads GET /v1/models (falling back to GET /api/v1/ais on deployments that have not shipped the OpenAI-compatible route yet) and shows the model id, purpose, context length, and pricing. No authentication required.

chat — send a chat message

bash aichaos chat "what is a llama?" echo "my context" | aichaos chat "summarize this" aichaos chat -m qwen3-7-plus --system "be terse" "explain rust ownership" aichaos chat "tell me a joke" --stream # stream tokens aichaos chat "tell me a joke" --json # full completion JSON

The prompt comes from the positional argument, or from stdin when the argument is - or omitted and stdin is piped. With --stream the CLI prints each token as it arrives (SSE); without it, the final message content is printed. Default model is the first chat model returned by /v1/models.

gen — queue an image generation

bash aichaos gen "a red fox in the snow" -m flux-schnell aichaos gen "a red fox in the snow" --width 1280 --height 720 --quantity 4 aichaos gen "make it purple" --image photo.png -m p-image-edit # img2img aichaos gen "a red fox" --wait --timeout 300 # poll to completion aichaos gen "a red fox" --json

Posts POST /api/v1/generations as multipart/form-data and prints the batch id and generation ids. --wait polls GET /api/v1/generations/:id until the image is ready, failed, or cancelled; progress is printed to stderr so stdout stays pipe-clean.

status — show generation status

bash aichaos status 42 aichaos status 42 --json

Reads GET /api/v1/generations/42 and prints status, model, prompt, and the signed image URL when ready.

download — download a generation image

bash aichaos download 42 # writes red-fox.png (from image URL) aichaos download 42 -o fox.png aichaos download 42 --timeout 300 --json

Polls the generation to completion, resolves the signed download URL, and streams the file to disk. The signed URL needs no authentication, and the CLI never forwards the API key to a redirect target host.

usage — account usage

bash aichaos usage aichaos usage --limit 50 --json

Reads GET /api/v1/account/usage and prints the authenticated account’s usage: generation count, Spark spend, LLM request/token counts, and LLM cost. On deployments that do not ship that endpoint yet it falls back to a summary of recent generations from GET /api/v1/generations.

balance — Spark credit balance

bash aichaos balance aichaos balance --json

Reads GET /api/v1/account/balances and prints free, paid, and total Spark credits. If the deployment does not expose the endpoint, the CLI reports that balance is unavailable and exits 5.

stdin prompt input

Any prompt-taking command accepts input on stdin:

bash cat notes.md | aichaos chat "fix the typos" printf 'a cozy cabin' | aichaos gen -m flux-schnell --wait --output …

--json output

--json is a global flag: aichaos models --json, aichaos chat --json, aichaos gen --json, aichaos status --json, aichaos download --json, aichaos usage --json, aichaos balance --json. It prints exactly one JSON document to stdout; all human-readable messages go to stderr, so pipelines stay clean.

Exit codes

Code Meaning
0 Success
1 Generic API or unexpected error
2 Usage error (unknown command, missing prompt/arguments)
3 Authentication / authorization failure (401, 403)
4 Rate limited (429)
5 Not found (404)
6 Server error (5xx)
7 Network / transport failure

Security

  • The API key is never printed. Error messages contain only the parsed API error text, never request headers or bodies.
  • Authorization is sent only to the configured base host. On cross-host redirects (e.g. image CDNs) the header is stripped.
  • TLS certificate verification is always on for HTTPS connections; there is intentionally no flag to disable it.
  • The config file can hold your key; keep its permissions restrictive (chmod 600 ~/.config/aichaos/config.json).

Development

  • Source: cli/lib/aichaos.rb and cli/lib/aichaos/*.rb
  • Executable: cli/bin/aichaos
  • Tests: bundle exec rspec spec/cli (no network; the HTTP transport is covered with WebMock stubs and the CLI with an in-memory transport)
  • Lint: bundle exec rubocop cli spec/cli