# Yalla documentation — full context > Every documentation page concatenated for agents that want complete context. # 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 ` — deploy the current project. - `yalla rollback --to ` — revert to a prior deployment. - `yalla jobs watch` — stream provisioning job state. - `yalla variables set ` — 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 ``` --- # Agent skills and local workflow > Pair a coding agent with the CLI and install Yalla agent skills. Yalla ships agent skills that wrap the CLI so coding agents can deploy, roll back, and inspect jobs through a stable contract. ## Install the skills ```bash yalla skills install ``` ## Local workflow pairing 1. Authenticate once with `yalla login`. 2. Point your agent at [`/llms.txt`](/llms.txt) for machine-readable context. 3. Let the agent run CLI commands with `--json` and parse the envelope. 4. Surface the `request_id` from any error back to the human operator. > [!NOTE] > Agents read this site without scraping HTML — every page has a `.md` mirror and the context bundles aggregate them. --- # Manifest schema > The yalla.toml fields that describe projects, environments, and services. A project is described by a `yalla.toml` manifest. The hierarchy is **organization → project → environment → service**. ## Example manifest **yalla.toml** ```toml [project] name = "billing-api" [[service]] name = "api" kind = "application" port = 8080 [[service]] name = "cache" kind = "database" engine = "redis" ``` ## Service kinds | kind | Description | | --- | --- | | application | A built-from-source app or prebuilt image. | | database | A managed stateful service. | | compose | A multi-container compose service. | > [!WARNING] > Never commit secret values to the manifest. Reference variables by name and set them with `yalla variables set`. --- # 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 ``` > [!CAUTION] > Destroying an environment is irreversible. The CLI requires an explicit confirmation flag before it proceeds. --- # Control-plane flows > Operate services visually with the topology canvas, inspector actions, and the timeline. The Yalla control plane is a visual workspace over the same resources the CLI manages. The topology canvas shows the **organization → project → environment → service** hierarchy, and every action goes through the same audited Yalla API as the `yalla` commands below. ## Find a resource on the canvas - Canvas nodes show service kind and status at a glance, never by color alone. - Select a node to open the contextual inspector with its actions and tabs. - Use the command palette for keyboard-first search, deploy, rollback, and navigation. ## Act from the inspector Deploy, rollback, start, stop, variables, domains, and backups live on the selected resource — not on scattered pages. Every inspector action has a CLI equivalent, so agents and humans share one mental model. Rolling back from the inspector equals: ```bash yalla rollback --to ``` ## Read the timeline The timeline joins deployments, provisioning jobs, audit events, and failures into one stream. Copy the `request_id` from any failed entry before you [escalate to support](/docs/support). > [!NOTE] > The canvas ships keyboard alternatives and a non-canvas summary list, so every flow stays operable without a pointer. --- # Logs and metrics > Stream service logs, read metrics, and trust honest unavailable states. Logs and metrics flow through the Yalla backend. Neither the CLI nor the control plane ever connects to private runtime infrastructure directly. ## Stream logs ```bash yalla logs --service api --env production --follow ``` Machine-readable log envelope for agents. ```bash yalla logs --service api --env production --since 1h --json ``` ## Read metrics ```bash yalla metrics --service api --env production --window 24h ``` Metrics cover CPU, memory, and request rates. The Metrics tab of the [control-plane inspector](/docs/control-plane) shows the same numbers from the same API. ## When data is unavailable > [!NOTE] > If a backend adapter has no live samples yet, Yalla shows an explicit empty or unavailable state instead of fabricated data — in the CLI, the control plane, and these docs. --- # Domains > Attach custom domains to a service, verify DNS, and get managed TLS. Every service gets a generated URL. Custom domains attach per service and environment, from the Domains tab of the [inspector](/docs/control-plane) or the CLI. ## Attach a domain ```bash yalla domains add app.example.com --service api --env production ``` ## Verify DNS The add command prints the DNS records to create. Check verification status at any time: ```bash yalla domains list --service api --env production ``` ## TLS certificates Certificates are issued and renewed automatically once DNS verifies. Yalla never asks you to paste private keys into the CLI or the browser. > [!WARNING] > Removing a domain takes its traffic offline immediately. The CLI requires explicit confirmation before it proceeds. --- # Backups > Create, schedule, and restore backups for database services. Services with the `database` kind support backups, from the Backups tab of the [inspector](/docs/control-plane) or the CLI. Backups also appear as lightweight attachments on the service node. ## Create a backup ```bash yalla backups create --service cache --env production ``` ## Restore List recent backups, then restore a known-good one by its ID: ```bash yalla backups list --service cache --env production ``` ```bash yalla backups restore --service cache --env production ``` > [!CAUTION] > Restoring replaces the current data of the service. Take a fresh backup first and confirm the target environment before you proceed. --- # Usage and billing visibility > See usage, limits, and invoices; the backend stays the quota authority. Usage and limit figures shown in the CLI and the control plane are advisory. The Yalla backend is the authority that enforces quotas and produces invoices. ## Check usage ```bash yalla usage --org ``` Add `--json` to read the same numbers as a stable [Yalla envelope](/docs/api-envelopes) instead of formatted text. ## Limits and quotas When a quota is exceeded the API answers with a stable code such as `E_RATE_LIMITED` — branch on the [error code](/docs/error-codes), not the message, and retry only when the catalog marks it safe. ## Invoices Invoices and plan details live in the billing section of the control plane. Public documentation never shows account-specific amounts or payment details. > [!NOTE] > If usage looks wrong, capture the `request_id` from the usage response and [escalate to support](/docs/support) — never guess at corrections. --- # Troubleshooting > Diagnose failed deploys and stuck jobs with the request_id as your key. ## A deploy failed 1. Read `error.code` from the [error envelope](/docs/api-envelopes). 2. Look the code up in the [error codes](/docs/error-codes) catalog. 3. Copy the `request_id` and include it in any support request. 4. Retry only if the code is marked retryable. ## A job looks stuck ```bash yalla jobs watch --env production ``` > [!NOTE] > Logs and metrics may be unavailable while an adapter is still wiring up. The CLI shows an honest "unavailable" state rather than fabricated data. --- # 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 ` and notify support. --- # Support escalation > Escalate issues with the request_id, the error code, and the right severity. Every failed request carries a `request_id` in its [error envelope](/docs/api-envelopes). It lets support trace the exact request without you sharing any secret. ## Before you escalate 1. Capture `error.code` and `request_id` from the failing response. 2. Look the code up in the [error codes](/docs/error-codes) catalog. 3. Retry once with backoff only if the code is marked retryable. 4. Note the deployment or job ID if the failure came from a deploy. ## Open a support request ```bash yalla support ticket --request-id ``` The same flow is available from the control plane: every error surface shows a copyable `request_id` next to its support link. ## What support can see Support sees request metadata, audit events, and job state — never secret variable values, tokens, or payment credentials. Those stay redacted end to end. > [!CAUTION] > If you suspect a secret was exposed, rotate it first with `yalla variables set `, then escalate with the request_id — see [security boundaries](/docs/security).