# Yalla documentation — core context

> Curated core pages for agents that need the essentials in one request.

# Quickstart

> Install the CLI, authenticate, and ship your first service in minutes.

Yalla deploys and operates services through **Yalla Runtime** and the **Yalla Deploy Engine**. This quickstart takes you from an empty machine to a running service. Agents can follow the same steps from the [CLI reference](/docs/cli).

## Install the CLI

Install globally.

```bash
npm install -g @yalla/cli
```

Verify the install.

```bash
yalla --version
```

## Authenticate

Sign in with a browser-based flow. The CLI stores a short-lived session token in your OS keychain — never in plaintext, and never in this documentation.

```bash
yalla login
```

## Ship your first service

From a project directory with a `yalla.toml` manifest, deploy to an environment. See the [manifest schema](/docs/manifest-schema) for every field.

```bash
yalla deploy --env staging
```

> [!NOTE]
> Deployments are asynchronous. Watch progress with `yalla jobs watch` or in the control plane.

---

# CLI commands

> Install the Yalla CLI and learn the commands agents use most.

## Install

```bash
npm install -g @yalla/cli
```

## Core commands

- `yalla login` — start a browser-based session.
- `yalla deploy --env <name>` — deploy the current project.
- `yalla rollback --to <deployment-id>` — revert to a prior deployment.
- `yalla jobs watch` — stream provisioning job state.
- `yalla variables set <KEY>` — set a variable (values are prompted, never logged).

## Machine-readable output

Add `--json` to any command for a stable [Yalla envelope](/docs/api-envelopes). Agents should parse the envelope rather than scraping human text.

```bash
yalla deploy --env staging --json
```

---

# API envelopes

> The yalla.output.v1 and yalla.error.v1 envelopes every response uses.

Every Yalla API response is wrapped in a stable, versioned envelope. Parse the envelope defensively and treat unknown `schema` versions as a compatibility warning.

## Success envelope

**yalla.output.v1**

```json
{
  "schema": "yalla.output.v1",
  "request_id": "req_01HZY…",
  "data": { "deployment_id": "dep_01HZY…", "status": "deploying" }
}
```

## Error envelope

**yalla.error.v1**

```json
{
  "schema": "yalla.error.v1",
  "request_id": "req_01HZY…",
  "error": { "code": "E_RATE_LIMITED", "message": "Too many requests", "hint": "Retry after the reset window." }
}
```

Always surface `request_id` in error UI and support requests. See [error codes](/docs/error-codes) for the full catalog.

---

# Error codes

> Stable error codes, what they mean, and whether a retry is safe.

Error codes are stable identifiers. Branch on `error.code`, not on the human message — the message text may change between releases.

## Catalog

| Code | Meaning | Retryable |
| --- | --- | --- |
| E_UNAUTHENTICATED | No valid session. | No |
| E_PERMISSION_DENIED | The caller lacks the required scope. | No |
| E_RATE_LIMITED | Too many requests in the window. | Yes, after reset |
| E_RUNTIME_UNAVAILABLE | Yalla Runtime is temporarily unavailable. | Yes |
| E_INTERNAL | An unexpected server error occurred. | Yes |

## Handle an error in a script

**Branch on the stable code, never the message**

```bash
code=$(yalla deploy --env staging --json | jq -r '.error.code // empty')
if [ "$code" = "E_RATE_LIMITED" ]; then
  sleep 30
  yalla deploy --env staging --json
fi
```

> [!WARNING]
> A retryable code is safe to retry with backoff. Non-retryable codes need a corrective action first.

---

# Deployment recipes

> Common deploy, promote, and rollback flows for agents and humans.

## Promote staging to production

```bash
yalla deploy --env production --from staging
```

## Roll back a bad deploy

List recent deployments, then roll back to a known-good one. Rollbacks are reversible and audited.

```bash
yalla deployments list --env production
```

```bash
yalla rollback --to <deployment-id>
```

> [!CAUTION]
> Destroying an environment is irreversible. The CLI requires an explicit confirmation flag before it proceeds.

---

# Security boundaries

> What Yalla never exposes, and how secrets and tokens are handled.

Yalla treats credentials as never-leave-the-backend data. This documentation, the CLI, and the control plane follow the same boundary.

## Never exposed

- API keys, bearer tokens, and session tokens are never stored in browser storage.
- Secret variable values are redacted after creation and never echoed back.
- Connection strings and private runtime provider names never appear in public docs.
- Logs, telemetry, and screenshots are scrubbed of secret-shaped values.

## Reporting an issue

Include the `request_id` from the [error envelope](/docs/api-envelopes) when you contact support — it lets us trace the request without exposing any secret.

> [!CAUTION]
> If you believe a secret was exposed, rotate it immediately with `yalla variables set <KEY>` and notify support.