# Aral Cloud for AI agents — getting started

Aral Cloud is managed end-to-end with one CLI: `aral`. Every command accepts
`-o json` (or `ARAL_OUTPUT=json`) and prints machine-readable JSON. Errors go
to stderr as `{"error": "..."}` and the exit code is non-zero.

## Install

    curl -fsSL https://aralcloud.uz/dl/install | sh    # or download from the console

## Authenticate

Ask your human for an API token (Console → Settings → API tokens, or they run
`aral auth token --all --name my-agent`), then:

    aral auth login --token nex_...     # stores it in ~/.aral/config.yaml
    aral auth whoami                    # verify

The CLI silently swaps the token for a short-lived session JWT and caches it in
`~/.aral/session.json`; you never manage that. `ARAL_TOKEN=nex_...` as an env
var works too and overrides the stored one.

## Model

- **Organization** — the billing boundary. A token acts in the org it was
  minted in.
- **Project** — a workspace inside the org. `aral project list`, and
  `aral project use <id>` saves the default. Resources you create land in the
  active project. An agent running beside other agents should pin its project
  per invocation with `ARAL_PROJECT=<id>` (or `--project <id>`) instead of
  `project use` — the env var wins and never touches shared state.
- **Money** — `aral billing balance` answers `{balance_cents, has_paid, ...}`
  in UZS tiyin (100 tiyin = 1 so'm). `has_paid:false` means creates will be
  refused with 402 — tell your human to top up.

## Conventions that hold everywhere

- List commands return a JSON array; get commands return one object; ids are
  UUIDs. Pass ids positionally: `aral server get <id>`.
- Create is asynchronous for anything that boots a VM: the response returns
  immediately with `status: pending|creating|configuring`; poll the `get`
  command until `active`/`ready` (10s interval is polite; a fresh VM takes
  ~2 minutes, a managed database or one-click app several).
- Deletes are immediate commands but teardown is asynchronous too.
- Regions today: `hel1` (Helsinki). `aral server regions` is authoritative.