# Commands

Every command of this `aircloud` build (`0.1.12`), as `aircloud help <command>` prints it. Exit status: 0 done, 1 refused or failed, 2 usage. The generators' own commands are in [generators.md](generators.md).

## Options every command takes

| option | |
|---|---|
| `--verbose` | Print every API and identity-provider exchange on stderr: method, URL (query values elided), status, duration, request and correlation ids |
| `--membership <membership>` | Act as this one of your memberships, by id (sent as X-Air-Membership; default: your only one) |

## `aircloud new`

Create a product directory in its conventional shape

```sh
aircloud new <slug> [--name <name>] [--site react|static] [--api] [--css tailwind|css] [--runtime js|rust] [--skip-git|-G] [--pretend]
```

| option | |
|---|---|
| `--name <name>` | The product's human name, in any script, written as aircloud.toml `name`: the site's title (default: the slug humanized). The slug stays the product's identity |
| `--site react\|static` | The site template (default: the product's [generators].site, else react) |
| `--api` | An API product: no site (excludes --site and --css) |
| `--css tailwind\|css` | The site's styling (default: tailwind for react, css for static) |
| `--runtime js\|rust` | The runtime of the generated code (default: the product's [generators].runtime, else js) |
| `-G, --skip-git` | Do not initialize a git repository, .gitignore or .gitattributes |
| `--pretend` | Write nothing: print each path as create, modify or remove |

```sh
aircloud new shop
aircloud new loja --name 'Loja da Ana'
aircloud new shop --api --runtime rust
aircloud new blog --site static
```

## `aircloud generate`

Add to the product in its shape (a generator)

Its subcommands are the generators: see [generators.md](generators.md).

## `aircloud destroy`

Remove what a generator added

Its subcommands are the generators: see [generators.md](generators.md).

## `aircloud check`

Validate the product with the platform's own engine

```sh
aircloud check [options]
```

| option | |
|---|---|
| `--json` | Print the violations as JSON |

```sh
aircloud check
aircloud check --json
```

## `aircloud i18n`

Translation keys a release would be refused for, keys no code uses, and the locale bundle the tests read

Subcommands: `bundle`, `missing`, `unused`.

### `aircloud i18n bundle`

Write the product's locale bundle, compiled by the platform's own builder, where the tests read it

```sh
aircloud i18n bundle
```

```sh
aircloud i18n bundle
```

### `aircloud i18n missing`

The product keys a release would be refused for (exit 1), then the platform defaults resolved to en

```sh
aircloud i18n missing
```

```sh
aircloud i18n missing
```

### `aircloud i18n unused`

The product keys no code references

```sh
aircloud i18n unused
```

```sh
aircloud i18n unused
```

## `aircloud routes`

The resolved route table, and which routes require an end-user session

```sh
aircloud routes
```

```sh
aircloud routes
```

## `aircloud schedules`

The functions' cron triggers (UTC)

```sh
aircloud schedules
```

```sh
aircloud schedules
```

## `aircloud signup`

Create an account (then verify the address and log in)

```sh
aircloud signup --email <address> --account <slug> [options]
```

| option | |
|---|---|
| `--email <address>` | Required. The owner's email address; a verification code is mailed to it |
| `--account <slug>` | Required. The account's unique name, the one `aircloud login --account` takes: lower-case letters, digits and inner hyphens |
| `--region <region>` | The region whose API to use, from the directory built into this CLI (default: the last one used, else the only region) |
| `--api <url>` | The Air-Cloud API origin, a development override of --region (default: AIRCLOUD_API) |

```sh
aircloud signup --email you@example.com --account acme
aircloud signup --email you@example.com --account acme --region lab1
```

## `aircloud login`

Log in as a Builder (browser or --device) or as a product's service account

```sh
aircloud login [options]
```

| option | |
|---|---|
| `--region <region>` | The region whose API to use, from the directory built into this CLI (default: the last one used, else the only region) |
| `--api <url>` | The Air-Cloud API origin, a development override of --region (default: AIRCLOUD_API) |
| `--account <slug>` | The account to log in to, by the slug chosen at signup (default: the last one, remembered in config.json) |
| `--device` | Log in on any browser with a code (the device grant), for a shell without one |
| `--service-account <key.json>` | Log in as the service account whose key file this is (never copied) |
| `--product <slug>` | Also select this product now |
| `--timeout <duration>` | How long to wait for the login in the browser or with the device code; the URL or code is printed again while waiting |

```sh
aircloud login --account acme
aircloud login --device
aircloud login --service-account key.json
```

## `aircloud logout`

Revoke the cached tokens and forget the session

```sh
aircloud logout
```

```sh
aircloud logout
```

## `aircloud accounts`

The accounts logged in on this machine, and the one commands act as outside a product folder

Subcommands: `list`, `use`.

### `aircloud accounts list`

Each logged-in account with its region and API; the selected one is marked *

```sh
aircloud accounts list
```

```sh
aircloud accounts list
```

### `aircloud accounts use`

Select the account commands act as outside a product folder naming one

```sh
aircloud accounts use <account> [options]
```

| option | |
|---|---|
| `--region <region>` | The region of the account's session (needed only when it is logged in in several) |

```sh
aircloud accounts use acme
aircloud accounts use acme --region lab1
```

## `aircloud whoami`

The account (or service account) this CLI acts as

```sh
aircloud whoami
```

```sh
aircloud whoami
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud products`

Your account's products, with their tenant, status and host (from any directory)

Subcommands: `show`, `authorize`, `delete`.

### `aircloud products show`

One product: its tenant, status and host

```sh
aircloud products show [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud products show
aircloud products show --product shop
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud products authorize`

Authorize a product of your account now, without releasing it, and print its tenant and host

```sh
aircloud products authorize <slug>
```

```sh
aircloud products authorize shop
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud products delete`

Delete a product of your account and everything it holds (type its slug to confirm)

```sh
aircloud products delete <slug> [options]
```

| option | |
|---|---|
| `--confirm <slug>` | Confirm with the product's slug instead of typing it (default: asked on stdin) |

```sh
aircloud products delete shop
aircloud products delete shop --confirm shop
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud account`

The account you are logged in to

Subcommands: `delete`.

### `aircloud account delete`

Close the account: every product, member and identity of it is erased (type its slug to confirm)

```sh
aircloud account delete [options]
```

| option | |
|---|---|
| `--confirm <slug>` | Confirm with the account's slug instead of typing it (default: asked on stdin) |
| `--wait` | Wait until the account is erased, then forget this machine's session |
| `--timeout <duration>` | How long --wait waits |

```sh
aircloud account delete
aircloud account delete --confirm acme --wait
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud release`

Create, inspect and move the product's releases

Subcommands: `create`, `list`, `show`, `artifacts`, `activate`, `promote`, `rollback`.

### `aircloud release create`

Release the working directory's product (or a git ref); creates the product when your account has none

```sh
aircloud release create [options]
```

| option | |
|---|---|
| `--git <url>` | Release this repository instead of the working directory (with --ref) |
| `--ref <ref>` | The git ref to release (with --git) |
| `--wait` | Wait until the release is verified, failed or superseded, printing each status and part transition (and a failed part's error code and log tail) |
| `--timeout <duration>` | How long --wait waits |
| `--product <slug>` | The product of a --git release |
| `--dry-run` | Validate as the upload would (against the product's environments when logged in, else offline) and list the files it would carry, with their sizes and the compressed total; nothing is uploaded or created |

```sh
aircloud release create --wait
aircloud release create --dry-run
aircloud release create --git https://gitlab.com/me/shop.git --ref main --product shop
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud release list`

The product's releases, newest first

```sh
aircloud release list [options]
```

| option | |
|---|---|
| `--limit <n>` | At most this many (default: the API's page) |
| `--cursor <c>` | Continue from this page cursor |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud release list
aircloud release list --limit 5
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud release show`

A release as the platform records it (status, parts, test runs, environments, activations)

```sh
aircloud release show <release> [options]
```

| option | |
|---|---|
| `--artifacts <dir>` | Write each test run's report and artifacts under this directory |
| `--json` | Print the release record as JSON, as the API returns it |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud release show 3f2a…
aircloud release show 3f2a… --artifacts ./reports
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud release artifacts`

A release's test-run artifacts: list them, or download them with --out

```sh
aircloud release artifacts <release> [options]
```

| option | |
|---|---|
| `--env <environment>` | The test run's environment (default: every run) |
| `--out <dir>` | Download into this directory |
| `--file <path>` | Download only this file (with --out) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud release artifacts 3f2a…
aircloud release artifacts 3f2a… --out ./artifacts
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud release activate`

Activate a release in an environment

```sh
aircloud release activate <release> --env <environment> [options]
```

| option | |
|---|---|
| `--env <environment>` | Required. The environment to activate it in |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud release activate 3f2a… --env <preview>
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud release promote`

Activate a verified release in production

```sh
aircloud release promote <release> [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud release promote 3f2a…
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud release rollback`

Move an environment back to its previous release (or to --to)

```sh
aircloud release rollback --env <environment> [options]
```

| option | |
|---|---|
| `--env <environment>` | Required. The environment to roll back |
| `--to <release>` | The release to roll back to (default: the previous one) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud release rollback --env production
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud environments`

The product's environments: production and the previews you create and destroy

Subcommands: `create`, `list`, `destroy`.

### `aircloud environments create`

Create a preview environment: its own data, secrets and host, empty until a release is activated in it

```sh
aircloud environments create <environment> [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud environments create staging
aircloud release activate 3f2a… --env staging
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud environments list`

The product's environments: name, kind and creation time

```sh
aircloud environments list [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud environments list
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud environments destroy`

Destroy a preview environment and everything it holds (type its name to confirm)

```sh
aircloud environments destroy <environment> [options]
```

| option | |
|---|---|
| `--confirm <slug>` | Confirm with the environment's name instead of typing it (default: asked on stdin) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud environments destroy staging
aircloud environments destroy staging --confirm staging
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud functions`

The product's deployed functions: list them, read one, invoke one

Subcommands: `list`, `show`, `invoke`.

### `aircloud functions list`

The product's functions and where each is deployed

```sh
aircloud functions list [options]
```

| option | |
|---|---|
| `--all` | Also list removed functions |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud functions list
aircloud functions list --all
aircloud functions list --product shop
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud functions show`

A function: the version each environment runs, its triggers, versions and recent lifecycle

```sh
aircloud functions show <function> [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud functions show hello
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud functions invoke`

Run a deployed function once: its response body on stdout, the verdict on stderr

```sh
aircloud functions invoke <function> [options]
```

| option | |
|---|---|
| `--env <environment>` | The environment to run it in (default: production) |
| `--method <method>` | The request method the function receives (default: POST) |
| `--path <path>` | The request path and query the function receives, starting with / (default: /) |
| `--header <name>=<value>` | A request header the function receives (repeatable) (repeatable) |
| `--data <json>\|@<file>\|-` | The payload, a JSON value: inline, read from a file, or from stdin (default: none, and the function receives no body) |
| `--at <org_path>` | The org node the invocation acts at, at or below yours (default: your node) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud functions invoke hello --data '{"name":"Ada"}'
aircloud functions invoke deals --method GET --path /deals --at /acme/sales
aircloud functions invoke items --method GET --path /items --header accept=application/json
aircloud functions invoke hello --data @payload.json
echo '[1,2]' | aircloud functions invoke sum --data -
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud logs`

The product's function invocations, oldest first: time, function, environment, status, duration, correlation id and logs

```sh
aircloud logs [options]
```

| option | |
|---|---|
| `--function <name>` | Only this function's invocations |
| `--env <environment>` | Only invocations in this environment |
| `--status <status>` | Only invocations whose status starts with this (ok, error, error:functions.guest_server_error) |
| `--response-status <class\|code>` | Only invocations the function answered with this HTTP status: a class (4xx) or a code (404); --status is the platform's verdict, where a 4xx answer is ok |
| `--source <domain>` | Only event invocations from this trigger-source domain (app, comms, flex) |
| `--correlation-id <id>` | Only the invocation with this correlation id (the one functions invoke prints) |
| `--since <time\|duration>` | Only invocations at or after this RFC 3339 time, or this long ago (15m, 2h) (default: the API's window) |
| `--limit <n>` | At most this many of the newest records per read (default: the API's page) |
| `--follow` | Keep reading new invocations until interrupted |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud logs --function hello --since 15m
aircloud logs --status error --follow
aircloud logs --correlation-id 0198a3c4-…
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud secrets`

The product's secrets (values are read from stdin, never shown)

Subcommands: `set`, `list`, `delete`.

### `aircloud secrets set`

Set a secret's value, read from stdin

```sh
aircloud secrets set <NAME> --env <environment|ci> [options]
```

| option | |
|---|---|
| `--env <environment\|ci>` | Required. The environment (or ci) the value is for |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud secrets set STRIPE_KEY --env production < key.txt
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud secrets list`

Which secrets are set (never their values)

```sh
aircloud secrets list [options]
```

| option | |
|---|---|
| `--env <environment\|ci>` | Only this scope |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud secrets list
aircloud secrets list --env production
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud secrets delete`

Delete a secret's value

```sh
aircloud secrets delete <NAME> --env <environment|ci> [options]
```

| option | |
|---|---|
| `--env <environment\|ci>` | Required. The environment (or ci) the value is deleted from |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud secrets delete STRIPE_KEY --env production
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud members`

The product's end users: list, invite, change, grant, remove and block, and review a node's access

Subcommands: `list`, `invite`, `update`, `grants`, `grant`, `revoke`, `memberships`, `remove`, `blocks`, `unblock`, `review`.

### `aircloud members list`

The memberships at or below your node, peers at your own node included: membership, user, email, node, roles, state (invited, active) and origin (invite, self-registration, workspace)

```sh
aircloud members list [options]
```

| option | |
|---|---|
| `--path <org-path>` | Only the memberships at or below this node |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud members list
aircloud members list --path /staff
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud members invite`

Invite a person by email and place a membership at a node with roles, scopes and a profile

```sh
aircloud members invite <email> --path <org-path> [options]
```

| option | |
|---|---|
| `--path <org-path>` | Required. The node to place the membership at, at or below yours |
| `--roles <role>,<role>` | The membership's roles, comma-separated keys of the product's [authenticate] roles (default: none) |
| `--scopes <scope>,<scope>` | The scopes the membership may delegate, comma-separated, a subset of yours (default: none) |
| `--profile <name>` | The profile, by its name at --profile-node |
| `--profile-node <org-path>` | The node the profile is defined at |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud members invite ada@example.com --roles admin,editor --path /staff
aircloud members invite ada@example.com --path /acme --scopes tenant:org --profile admin --profile-node /
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud members update`

Change a membership's roles, node or scopes: each option given replaces that facet

```sh
aircloud members update <membership> [options]
```

| option | |
|---|---|
| `--roles <role>,<role>` | The membership's roles, comma-separated ("" for none) |
| `--path <org-path>` | The node to move the membership to, at or below yours |
| `--scopes <scope>,<scope>` | The scopes the membership may delegate, comma-separated ("" for none) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud members update 0198a3c4-… --roles viewer
aircloud members update 0198a3c4-… --path /staff/night --scopes ""
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud members grants`

A membership's grants: each profile it holds, at which node, until when

```sh
aircloud members grants <membership> [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud members grants 0198a3c4-…
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud members grant`

Grant a membership a profile at a node, optionally until a time

```sh
aircloud members grant <membership> --path <org-path> --profile <name> --profile-node <org-path> [options]
```

| option | |
|---|---|
| `--path <org-path>` | Required. The node the grant is placed at |
| `--profile <name>` | Required. The profile, by its name at --profile-node |
| `--profile-node <org-path>` | Required. The node the profile is defined at |
| `--expires-at <RFC 3339>` | When the grant stops authorizing (default: never) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud members grant 0198a3c4-… --path /staff --profile editor --profile-node / --expires-at 2027-01-31T00:00:00Z
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud members revoke`

Revoke one of a membership's grants

```sh
aircloud members revoke <membership> <grant> [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud members revoke 0198a3c4-… 0198a3c5-…
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud members memberships`

One person's memberships you may see, by user id

```sh
aircloud members memberships <user> [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud members memberships 2891…
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud members remove`

Remove a membership (type its id to confirm); --block keeps the address from registering again

```sh
aircloud members remove <membership> [options]
```

| option | |
|---|---|
| `--block` | Also block the member's address from registering again |
| `--confirm <slug>` | Confirm with the membership id instead of typing it (default: asked on stdin) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud members remove 0198a3c4-…
aircloud members remove 0198a3c4-… --block --confirm 0198a3c4-…
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud members blocks`

The blocked addresses at or below your node, peer removals at your own node included: email, node, who blocked it and when

```sh
aircloud members blocks [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud members blocks
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud members unblock`

Lift the block on an address, so it may register again

```sh
aircloud members unblock <email> [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud members unblock ada@example.com
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud members review`

A node's access review: grants expiring within --window, profiles no grant references, groups with no member, and who holds tenant:org

```sh
aircloud members review --window <duration> [options]
```

| option | |
|---|---|
| `--node <org-path>` | The node to review, at or below yours (default: your node) |
| `--window <duration>` | Required. How far ahead to look for expiring grants, a duration (720h) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud members review --window 720h
aircloud members review --node /acme --window 168h
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud org`

The product's org tree: the nodes its members, grants and data live at

Subcommands: `nodes`.

### `aircloud org nodes`

The nodes below yours: list, create, rename, archive, unarchive and delete

Subcommands: `list`, `create`, `rename`, `archive`, `unarchive`, `delete`.

#### `aircloud org nodes list`

The nodes strictly below yours: path, display name, status (active, archived), when archived, who created it and when, and a seeded node's seed (applied, or refused or failed with its reason)

```sh
aircloud org nodes list [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud org nodes list
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

#### `aircloud org nodes create`

Create a node strictly below yours

```sh
aircloud org nodes create <org-path> [options]
```

| option | |
|---|---|
| `--name <display-name>` | The node's name for people (1 to 100 characters) |
| `--seed <template>` | A node seed template to apply at the new node (with --environment) |
| `--environment <environment>` | The environment whose active release the seed template is resolved from (with --seed) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud org nodes create /acme
aircloud org nodes create /marcas --name Marcas
aircloud org nodes create /acme --seed company --environment production
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

#### `aircloud org nodes rename`

Change the display name of a node strictly below yours

```sh
aircloud org nodes rename <org-path> --name <display-name> [options]
```

| option | |
|---|---|
| `--name <display-name>` | Required. The node's new name for people (1 to 100 characters) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud org nodes rename /marcas --name "Marcas e Lojas"
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

#### `aircloud org nodes archive`

Archive a node: everything acting at or below it is suspended, reversibly

```sh
aircloud org nodes archive <org-path> [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud org nodes archive /acme
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

#### `aircloud org nodes unarchive`

Unarchive a node: its authority is restored as it was

```sh
aircloud org nodes unarchive <org-path> [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud org nodes unarchive /acme
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

#### `aircloud org nodes delete`

Erase an archived node and everything at or below it (type its path to confirm)

```sh
aircloud org nodes delete <org-path> [options]
```

| option | |
|---|---|
| `--confirm <slug>` | Confirm with the node's path instead of typing it (default: asked on stdin) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud org nodes delete /acme
aircloud org nodes delete /acme --confirm /acme
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud profiles`

The product's profiles: named role sets a grant confers at a node

Subcommands: `list`, `put`, `remove`.

### `aircloud profiles list`

The profiles visible at a node: node, name, roles and origin (declared, runtime)

```sh
aircloud profiles list [options]
```

| option | |
|---|---|
| `--node <org-path>` | The node, at or below yours (default: your node) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud profiles list
aircloud profiles list --node /acme
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud profiles put`

Create or replace a runtime profile at a node with its roles

```sh
aircloud profiles put --node <org-path> --name <name> --roles <role>,<role> [options]
```

| option | |
|---|---|
| `--node <org-path>` | Required. The node it is defined at |
| `--name <name>` | Required. Its name at --node |
| `--roles <role>,<role>` | Required. The profile's roles, comma-separated keys of the product's [authenticate] roles |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud profiles put --node /acme --name auditor --roles viewer,exporter
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud profiles remove`

Remove a runtime profile no grant references

```sh
aircloud profiles remove --node <org-path> --name <name> [options]
```

| option | |
|---|---|
| `--node <org-path>` | Required. The node it is defined at |
| `--name <name>` | Required. Its name at --node |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud profiles remove --node /acme --name auditor
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud groups`

The product's groups: memberships that share grants

Subcommands: `list`, `create`, `delete`, `members`, `add`, `remove`, `grants`, `grant`, `revoke`.

### `aircloud groups list`

The groups at or below your node

```sh
aircloud groups list [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud groups list
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud groups create`

Create a group at a node

```sh
aircloud groups create --node <org-path> --name <name> [options]
```

| option | |
|---|---|
| `--node <org-path>` | Required. The node it is defined at |
| `--name <name>` | Required. Its name at --node |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud groups create --node /acme --name night-shift
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud groups delete`

Delete a group with no member and no grant

```sh
aircloud groups delete --node <org-path> --name <name> [options]
```

| option | |
|---|---|
| `--node <org-path>` | Required. The node it is defined at |
| `--name <name>` | Required. Its name at --node |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud groups delete --node /acme --name night-shift
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud groups members`

A group's memberships

```sh
aircloud groups members --node <org-path> --name <name> [options]
```

| option | |
|---|---|
| `--node <org-path>` | Required. The node it is defined at |
| `--name <name>` | Required. Its name at --node |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud groups members --node /acme --name night-shift
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud groups add`

Add a membership to a group

```sh
aircloud groups add <membership> --node <org-path> --name <name> [options]
```

| option | |
|---|---|
| `--node <org-path>` | Required. The node it is defined at |
| `--name <name>` | Required. Its name at --node |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud groups add 0198a3c4-… --node /acme --name night-shift
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud groups remove`

Remove a membership from a group

```sh
aircloud groups remove <membership> --node <org-path> --name <name> [options]
```

| option | |
|---|---|
| `--node <org-path>` | Required. The node it is defined at |
| `--name <name>` | Required. Its name at --node |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud groups remove 0198a3c4-… --node /acme --name night-shift
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud groups grants`

A group's grants

```sh
aircloud groups grants --node <org-path> --name <name> [options]
```

| option | |
|---|---|
| `--node <org-path>` | Required. The node it is defined at |
| `--name <name>` | Required. Its name at --node |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud groups grants --node /acme --name night-shift
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud groups grant`

Grant a group a profile at a node, optionally until a time

```sh
aircloud groups grant --node <org-path> --name <name> --path <org-path> --profile <name> --profile-node <org-path> [options]
```

| option | |
|---|---|
| `--node <org-path>` | Required. The node it is defined at |
| `--name <name>` | Required. Its name at --node |
| `--path <org-path>` | Required. The node the grant is placed at |
| `--profile <name>` | Required. The profile, by its name at --profile-node |
| `--profile-node <org-path>` | Required. The node the profile is defined at |
| `--expires-at <RFC 3339>` | When the grant stops authorizing (default: never) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud groups grant --node /acme --name night-shift --path /acme --profile editor --profile-node /
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud groups revoke`

Revoke one of a group's grants

```sh
aircloud groups revoke <grant> --node <org-path> --name <name> [options]
```

| option | |
|---|---|
| `--node <org-path>` | Required. The node it is defined at |
| `--name <name>` | Required. Its name at --node |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud groups revoke 0198a3c5-… --node /acme --name night-shift
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud denies`

The product's denies: roles or operations refused at and below a node, whatever a grant confers

Subcommands: `list`, `create`, `delete`.

### `aircloud denies list`

The denies below your node

```sh
aircloud denies list [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud denies list
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud denies create`

Deny roles and/or operations at a node, on one entity or every entity

```sh
aircloud denies create --path <org-path> [options]
```

| option | |
|---|---|
| `--path <org-path>` | Required. The node the deny binds at and below |
| `--roles <role>,<role>` | The roles it removes, comma-separated |
| `--ops <op>,<op>` | The operations it refuses, comma-separated (entity.read, entity.create, entity.update, entity.delete) |
| `--entity <entity>` | Only this entity (default: every entity) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud denies create --path /acme --ops entity.delete --entity orders
aircloud denies create --path /acme/interns --roles admin
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud denies delete`

Lift a deny

```sh
aircloud denies delete <deny> [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud denies delete 0198a3c6-…
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud authz`

Why a principal may or may not act at a node, and who reaches a node: the platform's own evaluator answers

Subcommands: `check`, `explain`, `who`.

### `aircloud authz check`

Whether the subject may perform the action at the node: the decision and its rule (exit 1 unless allow)

```sh
aircloud authz check --sub <sub> --plane <plane> --node <org-path> --action <op> [options]
```

| option | |
|---|---|
| `--sub <sub>` | Required. The subject asked about: its principal id (an end user's or service account's sub) |
| `--plane <plane>` | Required. The plane the subject would act on, as its token names it (such as end_user) |
| `--subject-membership <membership>` | The membership the subject would select (default: its only one) |
| `--node <org-path>` | Required. The node it would act at, at or below yours |
| `--action <op>` | Required. The operation (entity.read, entity.create, entity.update, entity.delete) |
| `--entity <entity>` | The entity it would act on (the record layer answers when given) |
| `--field <field>` | A field of --entity |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud authz check --sub 2891… --plane end_user --node /acme --action entity.delete --entity orders
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud authz explain`

The whole answer: decision, deciding rule or refusal, the layer that decided, membership, roles, scopes and the record layer's detail

```sh
aircloud authz explain --sub <sub> --plane <plane> --node <org-path> --action <op> [options]
```

| option | |
|---|---|
| `--sub <sub>` | Required. The subject asked about: its principal id (an end user's or service account's sub) |
| `--plane <plane>` | Required. The plane the subject would act on, as its token names it (such as end_user) |
| `--subject-membership <membership>` | The membership the subject would select (default: its only one) |
| `--node <org-path>` | Required. The node it would act at, at or below yours |
| `--action <op>` | Required. The operation (entity.read, entity.create, entity.update, entity.delete) |
| `--entity <entity>` | The entity it would act on (the record layer answers when given) |
| `--field <field>` | A field of --entity |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud authz explain --sub 2891… --plane end_user --node /acme --action entity.update --entity orders --field total
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud authz who`

Every membership you may see whose authority reaches the node, with its roles there and the rule

```sh
aircloud authz who --node <org-path> [options]
```

| option | |
|---|---|
| `--node <org-path>` | Required. The node, at or below yours |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud authz who --node /acme
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud service-accounts`

The product's service accounts: the durable credential of a host with no keychain, such as CI

Subcommands: `list`, `create`, `rotate`, `delete`.

### `aircloud service-accounts list`

The service accounts you may manage: user, node, scopes, when the latest key expires, and who created it

```sh
aircloud service-accounts list [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud service-accounts list
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud service-accounts create`

Create a service account at a node with scopes, and write its key file

```sh
aircloud service-accounts create --org-path <org-path> --scopes <scope>,<scope> --out <key.json> [options]
```

| option | |
|---|---|
| `--org-path <org-path>` | Required. The node the account acts at, at or below yours |
| `--scopes <scope>,<scope>` | Required. The account's scopes, comma-separated: a subset of yours, never tenant:service-accounts |
| `--expires-at <RFC 3339>` | When the key expires, at most the platform's ceiling (default: the ceiling) |
| `--out <key.json>` | Required. Where to write the private key file (mode 600; never overwritten): what aircloud login --service-account reads |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud service-accounts create --org-path /ci --scopes tenant:deploy --out ci-key.json
aircloud service-accounts create --org-path /ci --scopes tenant:deploy --expires-at 2027-01-31T00:00:00Z --out ci-key.json
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud service-accounts rotate`

Register a new key for a service account and write its key file

```sh
aircloud service-accounts rotate <user> --out <key.json> [options]
```

| option | |
|---|---|
| `--revoke-key <key-id>` | The key id the new key replaces, revoked now (default: it stays valid until it expires) |
| `--expires-at <RFC 3339>` | When the key expires, at most the platform's ceiling (default: the ceiling) |
| `--out <key.json>` | Required. Where to write the private key file (mode 600; never overwritten): what aircloud login --service-account reads |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud service-accounts rotate 2891… --out ci-key-2.json
aircloud service-accounts rotate 2891… --revoke-key 2904… --out ci-key-2.json
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud service-accounts delete`

Revoke a service account and every key it holds (type its user id to confirm)

```sh
aircloud service-accounts delete <user> [options]
```

| option | |
|---|---|
| `--confirm <slug>` | Confirm with the account's user id instead of typing it (default: asked on stdin) |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud service-accounts delete 2891…
aircloud service-accounts delete 2891… --confirm 2891…
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud git-credentials`

The git read credential a private repository's `release create --git` is fetched with

Subcommands: `set`, `delete`.

### `aircloud git-credentials set`

Set the credential; the token is read from stdin

```sh
aircloud git-credentials set --username <user> [options]
```

| option | |
|---|---|
| `--username <user>` | Required. The git username the token belongs to |
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud git-credentials set --username alice < token.txt
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

### `aircloud git-credentials delete`

Delete the credential

```sh
aircloud git-credentials delete [options]
```

| option | |
|---|---|
| `--product <slug>` | The product to act on (default: the product of the working directory) |

```sh
aircloud git-credentials delete
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud test`

The product's api tests

Subcommands: `run`, `redeem`, `prepare`.

### `aircloud test run`

Run the integration layer against a product host

```sh
aircloud test run --base-url <url> [options]
```

| option | |
|---|---|
| `--base-url <url>` | Required. The product host the scenarios call |
| `--layer integration` | The layer to run (this executor runs integration) |
| `--resolve <host>:<port>:<address>` | Dial host:port at address, keeping the URL's host for SNI and Host (repeatable) (repeatable) |
| `--format text\|json` | json prints one test-report layer document on stdout |
| `--dir <dir>` | The directory holding test/ (default: the product root) |
| `--report <file>` | Also write the whole test-report document here |
| `--sessions <file>` | The verification sessions `test redeem` wrote; steps with `as` act as their principal (without it they are skipped) |

```sh
aircloud test run --base-url https://shop-abc123.example.com
```

### `aircloud test redeem`

Redeem a verification run's principal tokens once, into a sessions file (the platform test-runner)

```sh
aircloud test redeem --base-url <url> --tokens <file> --sessions <file> [options]
```

| option | |
|---|---|
| `--base-url <url>` | Required. The run's ci- product host |
| `--tokens <file>` | Required. The principals' tokens, {"<name>": "<token>"} |
| `--sessions <file>` | Required. Where the sessions are written (mode 0600) |
| `--resolve <host>:<port>:<address>` | Dial host:port at address, keeping the URL's host for SNI and Host (repeatable) (repeatable) |

```sh
aircloud test redeem --base-url https://shop-abc123--ci-7.example.com --tokens /air/principals/tokens.json --sessions /tmp/air/sessions.json
```

### `aircloud test prepare`

Prepare the unit layer as the release build does: write the compiled schema the tests declare from and the entries they invoke through, and link each JavaScript function's declared components

```sh
aircloud test prepare
```

```sh
aircloud test prepare
```

## `aircloud skill`

The AI-Skill that teaches your coding agent this CLI: install it, show it, check it

Subcommands: `install`, `show`, `doctor`.

### `aircloud skill install`

Install the skill for your coding agent (and register the dev MCP server with it)

```sh
aircloud skill install [options]
```

| option | |
|---|---|
| `--agent <claude\|codex\|gemini\|copilot\|cursor>` | The agent to install for |
| `--dir <path>` | Install under this root instead of the agent's skills directory (an unlisted agent, or a project) |
| `--detect` | Install for every supported agent found on this machine |
| `--prompt` | With --detect, ask before each agent |
| `--with-mcp` | Also register the dev MCP server with the agent (on; --with-mcp=false skips it) |

```sh
aircloud skill install --agent claude
aircloud skill install --detect --prompt
aircloud skill install --dir ./.claude/skills
```

### `aircloud skill show`

Print the skill's SKILL.md

```sh
aircloud skill show
```

```sh
aircloud skill show
```

### `aircloud skill doctor`

Check that the region speaks contracts compatible with this CLI's and every installed copy of the skill is this CLI's and follows it

```sh
aircloud skill doctor [options]
```

| option | |
|---|---|
| `--region <region>` | The region whose API to use, from the directory built into this CLI (default: the last one used, else the only region) |
| `--api <url>` | The Air-Cloud API origin, a development override of --region (default: AIRCLOUD_API) |

```sh
aircloud skill doctor
aircloud skill doctor --region lab1
```

## `aircloud feedback`

Report a platform problem or give feedback, with this CLI's session (shows what it sends, then asks)

Subcommands: `list`.

### `aircloud feedback list`

Your account's reports, newest first: status (received, triaged, resolved) and issue

```sh
aircloud feedback list [options]
```

| option | |
|---|---|
| `--limit <n>` | At most this many (default: the API's page) |

```sh
aircloud feedback list
```

Calls the Air-Cloud API: it needs a login (`aircloud login`).

## `aircloud mcp`

Serve the dev MCP server over stdio, for your coding agent to launch

```sh
aircloud mcp
```

```sh
aircloud mcp
```

## `aircloud upgrade`

Replace this binary with the latest signed release (or the one --version names)

```sh
aircloud upgrade [options]
```

| option | |
|---|---|
| `--version <x.y.z>` | Install this release, even one older than the running binary (default: the latest) |

```sh
aircloud upgrade
aircloud upgrade --version <version>
```

## `aircloud changelog`

This binary against the latest release: every newer release's notes, the upgrade, and this release's own notes

```sh
aircloud changelog [options]
```

| option | |
|---|---|
| `--check` | Exit 1 when a newer release exists |
| `--json` | Print the report as JSON |

```sh
aircloud changelog
aircloud changelog --check
aircloud changelog --json
```

## `aircloud version`

The release this binary is, the day it was released, and the control-plane build it was made from

```sh
aircloud version
```

```sh
aircloud version
```

## `aircloud help`

A command's usage, options and examples

```sh
aircloud help [<command>…]
```

```sh
aircloud help generate function
```

---

Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e.