# The acting node and elevation Every invocation of a function acts at exactly **one node** of your product's organization tree. The records it reads and writes, the mail it sends, the events it publishes, what it is metered against and what its log says are all at that node. This page says which node that is, how a function moves below it, how it manages the tree, and how it may count records it cannot read. ## Which node an invocation acts at | the invocation | acts at | |---|---| | a route inside `[authenticate]` (a session) | the home of the end user's selected membership | | a public `[[route]]` in `config/routes.toml` | the route's `org_path` | | an event trigger (`[[triggers.events]]` in `function.toml`) | the trigger's `org_path` | | a cron trigger (`[[triggers.cron]]`) | the trigger's `org_path` | | `aircloud functions invoke` | your own node (the membership you act through), or with `--at ` a node at or below it | A public route, an event trigger and a cron trigger have no end user, so they **must declare** their node: ```toml [[route]] prefix = "/api/hooks" function = "accounts" org_path = "/crm" ``` ```toml [[triggers.cron]] schedule = "0 3 * * *" org_path = "/crm/companies" [[triggers.events]] topic = "accounts.opened" org_path = "/" ``` `aircloud check` refuses an entry without one: `route.org_path_required`, `trigger.org_path_required`. `/`, the root, is a valid choice only when you write it — nothing defaults to it, so acting over every customer of the product is always visible in your repository. The generators write `org_path = "/"` on every route and trigger they add; edit it to act lower. A route to a container runs no function and declares none (`route.org_path_not_invocation`). ### Every node you name is declared A node exists only when something creates it, so every node your repository names — a public route's or a trigger's `org_path`, an `[mcp]` facet's `org_path`, an `[[authenticate.route]]`'s `at` — must be one each production activation creates, or one created at run time below a declared parent: | you may name | because | |---|---| | `/` | the tenant root always exists | | `admin_org_path`, `default_org_path`, the `[authenticate.workspaces]` parent, every `[authenticate] nodes` entry, and each of their ancestors | each production activation creates them ([Members and roles](members.md)) | | any node strictly below the `[authenticate.workspaces]` parent | workspace signup creates those at run time ([Workspaces](workspaces.md)) | `aircloud check` refuses any other node (`org.path_undeclared`), so a product never fails at run time on a node nothing created. To act at a fixed node of your own, declare it: ```toml [authenticate] nodes = ["/crm", { path = "/crm/companies", display_name = "Empresas" }] ``` An entry is the node's path, or `{ path, display_name }` to name it for people: each production release sets the declared name on the node. A node below a fixed node is not declared by it: declare that node too. A node created by a function through `nodes.create` outside the workspaces parent exists only once the function has run, so declare it in `nodes` if your repository names it. Removing a node from `nodes` never deletes it: archiving and erasing a node are your explicit acts (`aircloud org nodes archive`, `aircloud org nodes delete`). A function with no end user is not owner-scoped: it reads every customer's owned records at or below its node, and what it writes is stored at its node ([Owner and shared entities](entities.md#requests-with-no-end-user)). An event trigger receives only the events published at or below its node. ## Narrowing — only downward A function may move to a node **at or below** the one it entered at, through the guest interface `acting-node`: `current()` answers the node the next call acts at, and `narrow(path)` moves there. A node above or beside the entry node is refused (`capability.forbidden`). Narrowing grants nothing; it only shrinks what the function already reaches. ```js import { current, narrow } from "aircloud:functions/acting-node@1.0.0"; // A nightly cron declared at /crm/companies, one client at a time. for (const company of companies) { narrow(company.org_path); // every read and write that follows acts at that client's node // … } ``` Moving between nodes inside the entry node's subtree is not widening, so a sweep declared once at a parent narrows to each child in turn. ## Managing the tree from a function A function manages nodes, members, profiles, groups, denies and workspaces through the platform's tree capabilities, with the authority of its acting node, and only through the operations it declares: ```toml [org] operations = ["nodes.create", "members.invite"] ``` `nodes.create` takes `{org_path, display_name?, seed?}`: a `display_name` names the new node for people (1 to 100 characters, no control character; `org_node_name_invalid` otherwise), and `nodes.list` answers each node's `display_name`, and the acting node's as `at_display_name`, when it has one. Each name is an area and one of its operations — `nodes.create`, `nodes.archive`, `members.invite`, `members.update`, `workspaces.create` and so on, one per operation the tree capabilities offer; `aircloud check` refuses a name that is not one of them (`org.operation_unknown`), and an undeclared call is refused at run time (`capability.forbidden`). A cron declared at `/` manages the whole tree; one declared at `/acme` manages only below `/acme`. A session function manages members with the end user's own authority, never more. ## Archived nodes When a node is archived (`aircloud org nodes archive`), everything acting at it or below stops: sessions, public routes, events, crons and direct invokes are refused with `org_node_archived` until you unarchive it. ## Elevated aggregates An owned entity keeps each customer's records to that customer. Some answers need a number across all of them — "1 seat left", "you are 2nd on the waitlist" — without showing anyone else's record. A session function declares exactly the aggregate it needs in `function.toml`: ```toml [[elevate]] entity = "booking" ops = ["count", "sum", "max"] filter = ["slot"] group_by = ["status"] fields = ["seats"] scope = "subtree" ``` | key | what it says | |---|---| | `entity` | the owned entity whose owner scope the aggregate lifts | | `ops` | the aggregate functions it may run: `count`, `sum`, `avg`, `min`, `max` | | `filter` | the fields it may filter on | | `group_by` | the fields it may group by | | `fields` | the fields `sum`, `avg`, `min` and `max` may aggregate | | `scope` | `node`: the records stored at the acting node; `subtree`: the acting node and below | The function calls `aggregate-elevated` of the `flex-query` capability. That one aggregate runs over every owner's records; every other read of the same invocation stays owner-scoped, and the tree, denies and field policy still apply. **No record and no owner can ever be named**: the record id, the entity's owner field and its unique fields are refused in every role (`elevate.field_identifier`), so the answer is a number over records nobody can single out. A call outside the declaration is refused (`capability.forbidden`), each use is recorded, and it is metered. `aircloud check` also refuses an unknown entity (`elevate.entity_missing`), operation (`elevate.op_invalid`), field (`elevate.field_unknown`) or scope (`elevate.scope_invalid`). A function with no end user is not owner-scoped to begin with, so an elevation declared for it lifts nothing. --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # The AI-Skill The CLI carries an AI-Skill: an Agent Skills bundle (`SKILL.md` and its references) that teaches a coding agent the CLI, the product grammar, the generators, and the rules and error codes. It is rendered from the same catalogs as this site's reference, by the very binary you run, so it always describes the CLI you have. ## Installing it ```sh aircloud skill install --agent claude aircloud skill install --detect --prompt aircloud skill install --dir ./.claude/skills ``` `--agent` installs for one agent; `--detect` installs for every supported agent found on the machine, and with `--prompt` asks before each. The skill is written to the agent's user skills directory, from any directory, with no session and no network: | agent | skill directory | MCP registration | |---|---|---| | `claude` | `~/.claude/skills/aircloud/` | `~/.claude.json` | | `codex` | `~/.agents/skills/aircloud/` | `~/.codex/config.toml` | | `gemini` | `~/.gemini/skills/aircloud/` | `~/.gemini/settings.json` | | `copilot` | `~/.copilot/skills/aircloud/` | `~/.copilot/mcp-config.json` | | `cursor` | `~/.cursor/skills/aircloud/` | `~/.cursor/mcp.json` | `--dir` writes the skill under another root instead, for an unlisted agent or a project. Installing also registers the [dev MCP server](mcp.md) with the agent as a user-scope stdio entry (command `aircloud`, arguments `mcp`); it pre-approves no tool. `--with-mcp=false` skips the registration. The CLI never overwrites a directory it did not write. A copy it wrote follows the `aircloud` installation that wrote it: when that installation's build changes — after `aircloud upgrade`, or after a downgrade — it re-renders the copy on its next run. Any other `aircloud` (a second installation on your PATH, a build you run from a checkout) leaves the copy as it is and tells you so; `aircloud skill install --agent ` makes the copy follow the `aircloud` you run it with. ## Reading and checking it ```sh aircloud skill show aircloud skill doctor ``` `skill show` prints the skill's `SKILL.md`. `skill doctor` checks that your region speaks the contracts this CLI was built for and that every installed copy of the skill is this CLI's; it exits 0 only when both hold, and names each domain or copy that differs. A difference means the CLI, the skill or the region is a different build: upgrade the CLI and reinstall the skill. --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # How authorization works Everything that decides who may do what in your product, on one page: the organization tree, memberships, profiles, grants, groups, denies, field policy, the node each request acts at, and elevation. Each section links to the guide that puts it to work. The short version: **a request acts at one node of your product's organization tree, with the authority its membership holds there, and the platform reads that authority on every request.** Your end user's token says only who they are; what they may do comes from the tree, never from the token and never from your code. A change to a member's authority takes effect within seconds, on the requests that follow, not at the next sign-in. ## The picture ```text / the root: your product's base profiles live here (config/profiles.toml) └── /org Ada's membership is homed here: roles admin, staff, customer ├── /org/customers Bea signed up here as a customer, and owns her own orders └── /org/acme a client node; deny: entity.delete on orders, binding Acme and below ├── /org/acme/sales Carl: membership at /org/acme, grant "editor" here until 31 Jan └── /org/acme/ops a group "night-shift" holds a grant of "viewer" here a request ─► acts at ONE node ─► denies there and above ─► roles there ─► owner / shared ─► field policy (its membership's (refuse first, (home roles (which records) (which fields) home, or the entry's whatever grants + grants at declared org_path) confer) or above it) ``` ## The pieces - **Nodes.** Your product's end users and their records live in a tree of nodes such as `/org`, `/org/customers` and `/org/acme`. A record is stored at the node its writer acts at. A session reaches the records at its node and below; an entity can narrow that to each user's own records or open an ancestor's records for reading ([Owner and shared entities](entities.md)). You create client nodes with `aircloud org nodes create` ([Members, roles and registration](members.md#nodes)). - **Memberships.** A person holds one or more memberships in your product. Each membership is homed at one node and holds roles there. One person's memberships never sit one inside another. Every request acts through one membership: a session switches it at `/_air/memberships`; the CLI takes `--membership` when you hold several ([Members, roles and registration](members.md#memberships-and-their-ids)). - **Roles** are the keys of your `[authenticate] roles` vocabulary. A route admits a session holding any of its roles ([Routes](routes.md)); an entity's `write_roles` decide who may write it ([Owner and shared entities](entities.md#roles-each-write-requires)). - **Profiles** are named sets of roles. The base profiles are declared in `config/profiles.toml`; runtime profiles are created at a node below the root ([Profiles and grants](profiles-and-grants.md)). - **Grants** confer a profile, by reference, at a node at or below a membership's home, optionally until a time. Changing a profile changes every grant that references it. - **Groups** are memberships that share grants: a group's grant reaches each member at or below both the grant's node and the member's own home. - **Denies** remove roles or refuse operations at and below a node, whatever any grant confers, and they bind every actor there: members, functions acting there, and you. - **Field policy** decides, per record, which fields are visible, writable and required ([Field policy](field-policy.md)). - **The acting node.** A function with no end user acts at the `org_path` its route or trigger declares, and may narrow to a node below it, never above ([The acting node and elevation](acting-node.md)). - **Elevation.** A declared aggregate may count or sum an owned entity across its owners without ever naming a record or an owner ([The acting node and elevation](acting-node.md#elevated-aggregates)). - **Workspaces.** A product may let any signed-in end user create a company of their own: a node and a new membership homed there ([Workspaces](workspaces.md)). ## Who decides, in what order The platform evaluates a request in this order. The first step that refuses ends it; `aircloud authz explain` prints which step decided and the `rule` it names. | step | what it reads | refuses with | the `rule` explain names | |---|---|---|---| | the membership | the selected membership, against the projection | `session_membership_required` (a session), `membership_required` (a direct caller) | — | | the node is active | the acting node and every ancestor | `org_node_archived` | — | | denies | every deny at the acting node and above | an op-deny refuses the operation; a role-deny removes the role before the next steps | `deny.op`, `deny.role` | | roles | the membership's home roles, its grants and its groups' grants at or above the record's node | `session_role_required` (a route's roles), `flex.role_required` (`write_roles`) | `home`, `grant.membership`, `grant.group`, `write_roles` | | records | `owner`, `shared` and the tree | a record outside the scope is not found | `owner` | | fields | the `[[policy]]` rules at the record's node | a hidden field is omitted; a non-writable change is `flex.forbidden` | `field_policy` | When the authority cannot be read in time, the request is refused (`session_authz_unavailable` on a session), never treated as "no restriction". ## Asking why ```sh aircloud authz explain --sub 2891… --plane end_user --node /org/acme --action entity.delete --entity orders aircloud authz who --node /org/acme aircloud members review --window 720h ``` `authz check` answers the decision and exits 1 unless it is an allow; `authz explain` prints the whole answer: the membership, its roles and scopes at the node, the step that decided and the record layer's detail. `authz who` lists every membership whose authority reaches a node, with its roles there. Each is answered by the same evaluator enforcement uses, over the nodes at or below yours. Your coding agent asks the same question through the dev MCP server's `authz_check` ([The dev MCP server](mcp.md)). --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # How the platform works Air-Cloud is the backend you build a product on without leaving it. Data, end-user sign-in, functions, releases, mail and the public front door come already wired together, and one CLI, `aircloud`, drives them from a product directory in a conventional shape. The point is the integration: the pieces know about each other, so you write your product, not the glue between services. This page explains the ideas the other guides assume. Each section links to the guide that puts it to work. ## Your account, your products, and their tenants - **Your account** is you, the Builder. `aircloud signup` creates it and `aircloud login` signs you in to it ([Getting started](getting-started.md), [Logging in](login.md)). - **A product** is one repository and everything it runs: its data, its functions, its site, its end users. `aircloud products` lists your account's products. - **Each product is its own tenant** of the platform: a hard boundary. One product's data, end users, secrets and keys are never reachable from another product, yours or anyone else's. - **Environments.** A product runs one release per environment. Every product has `production`; other environments are previews you activate releases in ([Releases and environments](releases.md)). ## The organization tree Inside a product, your end users live in an **organization tree** that you shape: nodes with paths such as `/org`, `/org/staff` and `/org/customers`. Each end user holds a **membership** homed at a node, with role keys from your vocabulary; one person may hold several, each at its own node. The tree decides what a request reaches. By default a session reads and writes the records of its node and of every node below it, and manages members at or below its node, conferring only roles it holds itself. An entity can narrow that to the records each user owns, open records kept higher up for reading, or hide and freeze fields record by record. Profiles, grants, groups and denies add roles at other nodes or take them away. The platform reads all of it on every request, never from the token ([How authorization works](authorization.md), [Owner and shared entities](entities.md), [Members, roles and registration](members.md)). ## Every request acts at one node Whatever starts it, a request acts at exactly one node, and what it reads, writes, sends and is billed for is at that node: - a **session** acts at the home of the end user's selected membership; - a **public route**, an **event trigger** and a **cron trigger** act at the `org_path` they declare; - `aircloud functions invoke` acts at your own node, or with `--at ` at a node at or below it. A route or trigger with no end user **must declare** its `org_path`: `aircloud check` refuses one without it (`route.org_path_required`, `trigger.org_path_required`). Writing `org_path = "/"` is the explicit choice to act at the root, over every customer; nothing defaults to it. A function may then narrow to a node below the one it was declared at — a nightly sweep declared at a parent visits each client in turn — and never widen ([The acting node and elevation](acting-node.md)). ## Staff and customers Your product's end users are not you. Your Builder identity runs the product; your end users use it. Even your own first admin account in the product is a separate end-user identity, invited at your declared admin node. Among end users, a common split is **staff** — people who run the product with you — and **customers** — people who use it. `aircloud generate authentication` writes that convention: roles `admin`, `staff` and `customer`, a base profile for each, admins at `/org`, staff invited, and, with open registration, customers signing themselves up at `/org/customers` with the `customer` role. Staff are not owner-scoped by default, so they see every customer's orders while each customer sees their own ([Members, roles and registration](members.md)). ## B2B2B: your clients get the same structure If your product serves other businesses, each of your clients is a node of the tree, such as `/org/acme`, with an admin of its own who invites and manages Acme's people below that node. Acme's people see Acme's data and never another client's, because the tree, not your code, draws the line. You pass the platform's structure on to your clients instead of rebuilding it: that is what B2B2B means here. A client node comes into being in one of three ways: - **you create it** with `aircloud org nodes create /org/acme`, then invite its admin with `aircloud members invite ada@acme.example --path /org/acme --scopes tenant:org --profile admin --profile-node /` ([Members, roles and registration](members.md#nodes)); - **your code creates it**: a function that declares the tree operation `nodes.create` creates nodes below the node it acts at ([The acting node and elevation](acting-node.md#managing-the-tree-from-a-function)); - **the client creates it**: with workspaces declared, any signed-in end user creates a company of their own and becomes its admin ([Workspaces](workspaces.md)). The client's admin can in turn manage Acme's own sub-nodes, profiles, groups and denies, the same way you manage yours, and never above Acme's node. Archiving a client's node suspends everything acting there until you unarchive it. ## The motors you meet The platform is built from a set of engines, called motors. These are the ones a product uses today: - **Air-Deploy — the product and its releases.** The CLI, the conventional product layout, the generators, `aircloud check`, and releases that build, test and activate your product per environment. Also the AI-Skill and the dev MCP server that teach your coding agent all of this ([Releases and environments](releases.md), [The AI-Skill](ai-skill.md), [The dev MCP server](mcp.md)). - **Air-Flex — your data.** You declare entities in `db/schema/.toml`; Air-Flex stores and validates the records, enforces required fields, enum values, defaults, owners and the tree's boundaries at one chokepoint that your code cannot skip ([Owner and shared entities](entities.md)). - **Air-Auth — sign-in and members.** End users sign in on the platform's hosted login, never on a password table of yours; roles and registration are declared in `config/routes.toml` ([Members, roles and registration](members.md), [Routes](routes.md)). - **Air-Functions — your code.** Functions run sandboxed, behind a route, on a schedule or on an event, and reach data, secrets and mail only through the platform's capabilities ([Logs and invoking functions](functions.md)). - **Air-Reflect — screens from your schema.** The site's resource pages render lists, details and forms from your entity declarations, so a field you add appears without copying it into a page. - **Air-Edge — the public front door.** TLS, the web application firewall and rate limits sized by your plan, in front of every product host. - **Air-Comms — mail.** The platform sends your end users' sign-in and verification mail, and a function can hand mail to it through its mail capability. - **Air-Billing — plans and metering.** Every metered action (a query, a record write, an invocation, a mail send) is counted against your product's plan (see below). Other motors are planned and not available yet: object storage (Air-Blob), analytics (Air-Insights), outbound connectors (Air-Connect), declarative automation flows (the flow generator is reserved and refuses), and billing your own customers through your own payment provider. ## Plans and allowances Every product runs on a plan. The plan declares, per metered action, how much is included and what happens past it: the action is refused with a typed error, or a warning to upgrade is raised, or the overage is counted, as the plan declares for that action. Your account's first products draw a free allowance. Mail is one such action. A free monthly allowance of **100 platform mail recipients** per product is **planned**: today the default plan includes no mail sends of its own. The sign-in and verification mail the platform sends to your end users is not one of your sends and will not count against that allowance. ## Sovereign infrastructure Air-Cloud runs on infrastructure the platform operates itself, not resold from a cloud provider: its own servers, its own keys, its own mail egress. For you it means the platform is not reselling another provider's services at a margin, which is what lets it bundle everything into one product, and that the keys signing what you install are held by the platform alone ([Installing and verifying the CLI](install.md)). You do not need to do anything about it; it is what makes the all-in-one affordable. --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Currency The currency a product charges is a fact of the product, declared once in `aircloud.toml` as an ISO 4217 code: ```toml [i18n] default_locale = "pt-BR" available_locales = ["pt-BR", "en"] currency = "BRL" ``` Formatting an amount with `numberToCurrency` renders it in the product's currency under every locale: the currency gives the code and the default number of fraction digits (its ISO 4217 minor unit — two for BRL, none for JPY), and the viewer's locale gives the symbol and the pattern. A product charging BRL shows reais to every visitor, as `R$ 1.234,50` in `pt-BR` and `R$1,234.50` in `en`. A call's `precision` overrides the fraction digits, and a call's `unit` formats an amount that is in another currency. The currency is never assumed. Without `[i18n] currency`, a release whose code formats a currency the build can see is refused, and a formatting call that only runs at run time renders the generic currency sign `¤`. A value that carries its own currency — an amount Air-Billing billed — is formatted in that currency, never in the product's default. --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Owner and shared entities An entity is declared by its file `db/schema/.toml`. What an end user's session may read and write of it follows from where the user sits in the organization tree, and from two declarations of the entity: `owner` and `shared`. They exclude each other. ## The default: at or below the user's node With neither key, every request of an end user reaches the records of their node and of every node below it. A record is stored at the node the request that created it acts at. ## Owned entities ```toml display_name = "Order" owner = "customer_sub" owner_bypass_roles = ["admin", "staff"] [fields.customer_sub] type = "string" [fields.total] type = "decimal" ``` `owner` names a `string` field of the entity that holds the owning end user's identity, one line. An end user then reaches only the records they own, and a record they create is owned by them whatever the request says. `owner_bypass_roles` lists roles of `[authenticate] roles` whose holders are not owner-scoped on this entity: that is how staff read every order. `aircloud check` refuses an `owner` field that does not exist or is not `string`, and a bypass role the vocabulary lacks. `aircloud generate scaffold` declares an owned entity with `--owner`; its bypass roles default to the vocabulary's roles other than `customer`: ```sh aircloud generate scaffold order total:decimal --owner customer_sub ``` ## Shared entities ```toml display_name = "Product" shared = true ``` Records of a `shared` entity stored at a node above the user's are **readable** by them — a catalogue kept at the top of the tree is read by every customer below it. Writes stay at or below the user's node. An owned entity can never be shared. ## Roles each write requires ```toml display_name = "Invoice" write_roles = { create = ["staff"], update = ["staff", "clerk"], delete = ["admin"] } ``` `write_roles` names, per operation, the roles an end user must hold to write a record: each list is any-of, each role a key of `[authenticate] roles` (`aircloud check` refuses another, `schema.write_role_undeclared`), and an operation it does not list needs no role. Air-Flex enforces it on every path a write takes: an end user holding none of the operation's roles at the record's node is refused `flex.role_required` (403, naming the entity, the operation and the roles that would admit it). It binds acting end users only, and never restricts reads — `owner` and `shared` decide those. ## Labels An entity's and a field's names are ASCII identifiers. Their label in the product's default locale is written verbatim with `--display-name` (the entity) and a field's `:display_name=` segment: ```sh aircloud generate model product price:decimal:display_name=Preço --display-name Produto ``` Without one, the label is the name humanized; under a default locale other than English, `aircloud i18n missing` lists every such label, since nobody wrote it. ## Requests with no end user A request carrying no end user's session — a public route, a cron or event trigger, `aircloud functions invoke`, seeds — has no end user to scope it. A function with no end user — on a public route, an event or a cron — acts at the node its org_path declares: `org_path` on the route in `config/routes.toml`, or on the trigger in its `function.toml`. `aircloud check` refuses an entry without one (route.org_path_required, trigger.org_path_required), and `org_path = "/"` acts at the root only because it is written; `aircloud functions invoke` acts at your own node or at the node below it that `--at` names ([The acting node and elevation](acting-node.md)). Such a function is not owner-scoped: it reads every customer's owned records at or below that node. Protect an owned entity's routes by placing them in `[authenticate]` (see [Routes](routes.md)). The records such a function writes are stored at that node. Sessions at a node below read them only when the entity is shared, and never write them. To let staff change such records, write them from a function that runs in the staff member's session (a route inside `[authenticate]`). ## Fields a member may see and change Which fields of a record a member sees, may change and must fill in is declared per field and per record: see [Field policy](field-policy.md). --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Environments A product runs in environments. Each one has its own data, secrets, release pointer and product host: - `production`, which every product has; - the **previews** you create and destroy; - `ci` and `ci-`, which belong to the platform. Each `ci-` is created for one release's verification run and destroyed when that run ends. ## Creating a preview ```sh aircloud environments create staging ``` A preview starts empty. It runs nothing until a release is activated in it: ```sh aircloud release activate --env staging ``` The name follows the environment grammar: lower-case letters, digits and single inner hyphens. `production`, `ci` and `ci-` are refused, naming the name, before anything is sent. The platform also refuses a name whose product host would not fit one DNS label (`host_label_too_long`). A name the product already has is refused as `conflict`. `config/environments/.toml` overrides keys for the environment of that name, and `config/environments/preview.toml` overrides them for every preview. An overlay changes an environment that exists; it never creates one. ## Listing them ```sh aircloud environments list ``` prints each environment's name, kind (`production` or `preview`) and creation time. ## Destroying a preview ```sh aircloud environments destroy staging ``` erases the preview's data, secrets, release pointer and host. It cannot be undone, so the command asks you to type the environment's name first. Pass `--confirm staging` to confirm without a prompt, for example in a script. `production` and the platform's `ci` environments are never destroyed this way. `aircloud functions list` counts the environments whose active release holds each function, so a function that lived only in a destroyed preview reads `removed` or `undeployed` once the preview is gone. --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Field policy `owner`, `shared` and `write_roles` decide which records a member reaches and may write ([Owner and shared entities](entities.md)). **Field policy** decides, record by record, which of a record's fields that member sees, may change, and must fill in. Air-Flex enforces it on every read and write, whatever path the request takes — a page, a function, the API or your coding agent — so your code never filters fields itself. ## Declaring rules Rules are `[[policy]]` tables of the entity's file, `db/schema/.toml`: ```toml [[policy]] field = "internal" effect = "visible" when = { ref = "actor.roles", op = "contains", value = "staff" } [[policy]] field = "seats" effect = "writable" when = { and = [{ ref = "record.status", op = "eq", value = "held" }, { ref = "env.now", op = "lt", value = "2027-01-01T00:00:00Z" }] } [[policy]] field = "slot" effect = "required" when = { ref = "actor.org_path", op = "in", value = ["/crm/companies"] } ``` | key | what it says | |---|---| | `field` | a field the entity declares | | `effect` | `visible`: the field is shown only where `when` holds; `writable`: it may be changed only where `when` holds; `required`: it must be filled in wherever `when` holds | | `when` | a condition: a leaf `{ ref, op, value }`, or `and` / `or` over a list of conditions | A leaf's `ref` reads one of: - `record.` — the record's own value (on a create, the value submitted; for `required`, the value the write would leave); - `actor.roles`, `actor.sub`, `actor.org_path` — the member acting, with **the roles they hold at the record's node**, not at their home ([How authorization works](authorization.md)); - `env.now` — the current time, in steps the platform declares, so a rule's answer does not change every instant; - `surface` — where the request came from: `api`, `mcp` (your coding agent), `import` (your repository's own data — see [below](#import-is-your-repository)), or the `ui.form` and `ui.table` your own pages declare. A `record.` leaf takes the operators a query filter takes on that field's type, and a condition is bounded in depth and size as a query filter is. `aircloud check` refuses a rule outside the grammar — an unknown key, effect, reference, operator or combinator, a field the entity does not declare, an operator its type refuses, a condition past the bounds — with `schema.policy_invalid`; there is no expression escape hatch. ## What a member sees - **Rules only take away.** Several rules on one field all apply: every `visible` and `writable` condition must hold, and any `required` condition that holds requires the field. A node below the root can add rules of its own that tighten yours, never relax them. - **A hidden field is omitted** from that record in every answer: a get, a list page, a query, an aggregate. - **A hidden field matches nothing.** A filter on a field hidden on a record never makes that record match, in either direction; a sort reads it as absent; an aggregate takes no value from it; a full-text or vector search never finds the record through it. Two records that differ only in a hidden value answer alike, so nothing leaks through a query. - **A field hidden for the whole request** — by a rule of yours that reads neither the record nor the member's roles — is refused up front when a query names it (`flex.forbidden`). - **A write that changes a field that is not writable** on that record is refused (`flex.forbidden`, naming the field, the effect and the node). Sending the value it already holds is not a change. ## `import` is your repository Data your repository declares — seed templates applied at a new node, your data migrations, and the test fixtures the release verification pipeline loads — arrives on the `import` surface. It is yours: the repository is the one writer of your schema, so **`visible` and `writable` rules do not apply to `import`**. A fixture or a migration can fill a field you guard for your members — a `stage` only a `manager` may change, say — without a rule that names `surface`. **`required` still applies**: a fixture, seed or migration that leaves a required field empty is refused (`flex.validation`). Everything that is not field policy still applies too: `write_roles`, `owner` and `shared`, the tenant and node a record belongs to, and denies. Only the platform puts a request on `import`. Nothing a page, a function, your coding agent or an API call sends — a header, a query parameter, a body value — makes a request `import`, so a rule that guards a field from your members guards it on every one of those paths. ## `ui.form` and `ui.table` are presentation Your own page declares the `ui.*` surface it renders, so a rule whose only difference between showing and hiding a field is `ui.form` against `ui.table` hides nothing from someone who calls the API and declares the other one. Use them to tidy a screen; protect a confidential field with `actor.*` or `record.*`. ## Asking why `aircloud authz explain … --entity --field ` names the rule that decided whether a member may act on one field at a node ([How authorization works](authorization.md#asking-why)). --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Logs and invoking functions ## Listing and reading functions ```sh aircloud functions list aircloud functions list --all aircloud functions show hello ``` `functions list` says what is live. A function is `deployed in N environments ()` while the active release of any environment, a preview included, holds it. With none, it is `removed` if a release active in production once held it, else `undeployed`. Removed functions are listed only with `--all`. `functions show` gives a function as deployed: the version each environment runs, its triggers, its versions and its recent lifecycle. ## Shared components Code several functions use is a component, not a copy: ```sh aircloud generate component pricing ``` writes `lib/pricing/`. A function composes it by listing it in its `function.toml` — `components = ["pricing"]` — and a JavaScript function imports it by name (`import { describe } from "pricing"`). The platform's build links it as the function's `node_modules/pricing` (a `file:` dependency is refused by the lockfile rules), and `aircloud test prepare` links it the same way for the tests. A listed component with no `lib//` fails the build `build.component_missing`; an installed package of the same name, `build.component_link_conflict`. ## Unit tests `npm --prefix test ci && npm --prefix test test` runs the unit layer. Its `pretest` runs `aircloud test prepare`, which compiles `db/schema/` to the file the testing double reads, so a generated test declares the product's real schema — owners, shared entities, defaults and write roles, placed at the root as the platform places them — with `world.flex.declareFromSchema()` after `world.reset()`. Do not also create a schema entity with `world.flex.defineEntity`: an entity created through the API is placed at the signed-in node, and the double refuses a schema declaration over one placed there. ## Time zones in functions The JavaScript function runtime has no `Intl`: any `Intl` call throws `ReferenceError: Intl is not defined`. A `Date`'s local time is UTC (`getTimezoneOffset()` is `0`), and `toLocaleString`, `toLocaleDateString` and `toLocaleTimeString` ignore the locale and the `timeZone` option. A function takes a zone's date and time from `civilDate` and `instantOf` in `@aircloudhq/web/function`, which read the rules of the zones the product declares from its locale bundle; the zone defaults to the `time_zone` declared in `aircloud.toml`: ```js import { i18nFor, civilDate, instantOf } from "@aircloudhq/web/function"; const i18n = await i18nFor(request, { function: "book" }); civilDate(i18n); // "2024-06-01": today, in time_zone civilDate(i18n, { at: "2024-06-01T02:30:00Z" }); // the date on the wall there at that instant instantOf(i18n, { date: "2024-06-01", time: "19:00" }); // a Date: when the wall clock there reads 19:00 ``` `instantOf` resolves a wall time the zone passes twice to the earlier instant and shifts one it skips forward by the gap. Never re-implement zone math — offsets, daylight saving — in function code. The unit tests' `invoke()` runs a function with the same `Intl` and time zone, so a test catches a call the runtime would refuse. ## Invoking a function ```sh aircloud functions invoke hello --data '{"name":"Ada"}' aircloud functions invoke hello --env --data @payload.json echo '[1,2]' | aircloud functions invoke sum --data - ``` `functions invoke` runs a deployed function once, in `production` unless `--env` names another environment: one of the product's previews, or a `ci-` while its verification run lasts (the platform destroys it when the run ends; see [Releases and environments](releases.md#other-environments)). The payload is a JSON value — inline, read from a file (`@file`), or from standard input (`-`) — and reaches the function as the body of a `POST /` with `Content-Type: application/json`. Without `--data` the function receives no body and no `Content-Type`; `--data 'null'` sends the JSON `null`. `--method`, `--path` and `--header name=value` (repeatable) name the request the function receives instead, so a function that routes by method and path is exercised as its clients call it: ```sh aircloud functions invoke items --method GET --path /items --header accept=application/json ``` The platform admits a closed set of methods and of headers (the content-negotiation ones: `content-type`, `accept`, `accept-language`) and bounds the length of the path and of each header; a request outside them is refused, naming the rule, before the function is called. A GET or HEAD has no body, so `--data` with one is refused; so is a `content-type` header without `--data`, or one that is not a JSON media type (`application/json`, `application/+json`): the payload is JSON. Each is refused before anything is sent, with exit status `2`. A function needs no route to be invoked. The function's response body is printed on standard output, and the verdict on standard error: ```text aircloud: ok · response 200 · billed · correlation 0198a3c4-… ``` The verdict is the platform's: the invocation's status, the function's response status, whether it was billed, and the correlation id its invocation record carries. The exit status says what the function answered: `0` for a 2xx or 3xx response, `3` for a 4xx, `4` for a 5xx or a refusal by the platform before the function ran, `1` when the CLI or the API failed and no verdict exists, `2` for a usage error. An invocation is metered and billed like any other. Payload and response are each capped at 1 MiB; a longer response is truncated. The platform screens every request to your product for known attacks before it reaches your function. A JSON or form body is screened up to a fixed number of values (the platform's published inspection bound). A larger body is still delivered whole, and the values past that point reach your function unscreened, so validate what your function reads from a payload rather than trusting its shape. A request whose query string carries an unusually large number of parameters is refused. The CLI never retries an invocation, except once with a renewed credential when an expired token was refused without billing. When the outcome cannot be read, the CLI says so and names the correlation id to settle it with: ```sh aircloud logs --correlation-id 0198a3c4-… ``` ## Reading the logs ```sh aircloud logs --function hello --since 15m aircloud logs --status error --follow aircloud logs --env production --source flex ``` `aircloud logs` lists the product's function invocations, oldest first. Each record is one line — time, function, environment, status, duration, trigger (`http`, `api`, `event` or `cron`) and correlation id — followed by the response status and the lines the function logged. The filters combine: | option | keeps | |---|---| | `--function ` | one function's invocations | | `--env ` | one environment's: the product's own, or a platform `ci`/`ci-` one | | `--status ` | those whose status starts with this: `ok`, `error`, `error:functions.guest_server_error` | | `--response-status ` | those the function answered with this HTTP status: a class (`4xx`) or a code (`404`) | | `--source ` | event invocations from one trigger-source domain (`aircloud help logs` lists them) | | `--correlation-id ` | the one invocation with this id | | `--since ` | those at or after an RFC 3339 time, or this long ago (`15m`, `2h`) | | `--limit ` | at most this many of the newest records per read | `--status` is the platform's verdict, where a function's own 4xx answer is `ok`; `--response-status` is what the function answered, so `--response-status 4xx` finds the requests it refused. An environment the product has no invocations for, or a source outside the trigger-source domains, is refused by the platform with `functions.invocation_filter_unknown`, naming the values it can be; the same refusal answers the API and the dev MCP server. `--follow` keeps reading new invocations, every few seconds, until you interrupt it. The codes a function's refusal can carry are on [Service error codes](../reference/service-errors.md). --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Getting started: from an empty directory to a running product This guide takes you from nothing to a product that is deployed, whose function you have run and whose logs you have read. Follow the steps in order; each shows what the CLI prints when it succeeds. You need macOS or Linux, `curl`, and `git` (the CLI initializes the product's repository; without `git` it warns and carries on). You do not need Node.js or Rust: the platform builds the product. ## 1. Install the CLI ```sh curl -fsSL https://get.simpleservices.com.br/install.sh | sh ``` The script installs `aircloud` into `~/.local/bin`, verifying the release's signature and checksum first. Check that it runs: ```sh aircloud version ``` Other channels (Homebrew, npm, Docker) and how to verify a release by hand: [Installing and verifying the CLI](install.md). ## 2. Install the AI-Skill for your coding agent (optional) On an interactive terminal the install script offers it. To do it yourself: ```sh aircloud skill install --detect --prompt ``` This teaches your coding agent the CLI and registers the dev MCP server with it: see [The AI-Skill](ai-skill.md). ## 3. Create your account Choose an account slug — lower-case letters, digits and inner hyphens — and sign up with your email address: ```sh aircloud signup --email you@example.com --account acme ``` The CLI prints `created account acme (…) for you@example.com` and the next step, the login command to run: ```text verify the address with the code mailed to it, then log in: aircloud login --account acme ``` A verification code is mailed to the address. No token is issued before the address is verified: the first login asks for the code. ## 4. Verify your address and log in ```sh aircloud login --account acme ``` Your browser opens the Air-Cloud login page. Sign in, and when it asks, enter the verification code mailed to you. On a machine without a browser, use `aircloud login --device` and confirm the printed code on any other device. While the CLI waits it prints the URL (or the code) again every 30 seconds, and it gives up after five minutes; `--timeout 15m` waits longer. The CLI prints `logged in to … as account acme (token valid until …)`. Confirm who you are: ```sh aircloud whoami ``` How the session is kept, and what changes on a machine without a keychain: [Logging in](login.md). ## 5. Create the product In an empty directory: ```sh aircloud new shop cd shop ``` `aircloud new` prints a `create ` line per file. The product `shop` has a React site under `app/site/`, one function (`health`, answering `GET /api/health`), its route table `config/routes.toml`, its tests under `test/`, `AGENTS.md` (the map your coding agent reads), and a git repository. ## 6. Add a function ```sh aircloud generate function hello --route /api/hello ``` This writes `app/functions/hello/` — the function, its `function.toml` and a unit test — adds the route `/api/hello` to `config/routes.toml`, and adds an integration scenario for it. The function answers every request with its name and the request's method. ## 7. Check the product ```sh aircloud check ``` `aircloud check` validates the product with the platform's own engine, offline. It prints `no violation`, or each violation with its rule; fix them before releasing (the rules: [Rules and error codes](../reference/errors.md)). ## 8. Release it ```sh aircloud release create --wait ``` The first release creates the product on your account and authorizes the CLI for it: the browser opens once more, labelled `authorizing product shop…`, and completes without a prompt while your login is fresh. On another machine, `aircloud products authorize shop` authorizes an existing product from any directory, without releasing anything. The release then uploads the working directory, and builds and tests it. The CLI prints `release (seq 1): `, then each status as it changes, and returns when the release is `verified` (or `failed`, with the command that shows why). A verified release is promoted to the `production` environment automatically; `aircloud release show ` lists its activations. See [Releases and environments](releases.md). A product that declares a secret (`aircloud generate secret`, or a webhook's `--verifier`) needs its value in the `ci` scope before a release can verify — the verification run reads `ci`, never production's values — and a value can be set only once the product exists, which the first release does. So its first release fails verification with `secret_unset`; set the values, then release again: ```sh aircloud secrets set STRIPE_KEY --env ci < key-for-tests.txt aircloud secrets set STRIPE_KEY --env production < key.txt aircloud release create --wait ``` ## 9. Run the function ```sh aircloud functions invoke hello --data '{"name":"Ada"}' ``` The response body is printed on standard output: ```json {"function":"hello","method":"POST"} ``` and the verdict on standard error: `aircloud: ok · response 200 · billed · correlation `. The exit status says what the function answered — `0` for 2xx or 3xx, `3` for 4xx, `4` for 5xx or a refusal by the platform — and a failed invocation names the correlation id to read in the logs when it left a record. ## 10. Read the logs ```sh aircloud logs --function hello --since 15m ``` Each invocation is one line — time, function, environment, status, duration, trigger (`trigger=api` for an invocation from the CLI) and correlation id — followed by its response status and the lines the function logged. ## Next - [Releases and environments](releases.md) — promoting, activating, rolling back, secrets. - [Logs and invoking functions](functions.md). - [Routes](routes.md) and [Members, roles and registration](members.md) — sessions, sign-in and end users. - The [Commands](../reference/commands.md) and [Generators](../reference/generators.md) reference. --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Translations (i18n) **Every user-visible text is a key in `config/locales`, never a literal in code.** That includes the values of `placeholder`, `title`, `aria-label`, `alt` and `label`, and toasts. `aircloud check` refuses a literal (`i18n.inline_text`). ## Locales ```toml [i18n] default_locale = "pt-BR" available_locales = ["pt-BR", "en"] fallbacks = { "pt-BR" = ["en"] } ``` `[i18n]` in `aircloud.toml` declares the default locale, the locales the product offers, and the locales a missing key falls back to. Without the section, the product is English only (`default_locale` `en`). The keys live in `config/locales/.yml`, or `config/locales/**/..yml` to split them by area. ## Where a key is looked up - **A page** reads its texts with `useT()`. A key that starts with a dot is the page's own: in `src/pages//index.jsx`, `t(".title")` reads `.index.title`. - **Sub-routes, components and layouts** use explicit, full keys, such as `t("components.cart.save")`. A key starting with a dot outside a page has no scope and throws. - **Outside React**, import `t` from `@aircloudhq/web/helpers/translation`. - **Functions answer codes, never sentences.** The site maps each code it can receive to a key, with one literal `t("…")` per code. Never compute a key (`t("errors." + code)`): a computed key is invisible to `aircloud i18n missing`. Dates and times go through `l()`, never `Intl`. Money goes through the product's currency: see [Currency](currency.md). ## Finding missing and unused keys ```sh aircloud i18n missing aircloud i18n unused ``` `i18n missing` lists the keys a release would be refused for, and exits 1 when there are any. `i18n unused` lists the keys no code references. ## The bundle the tests read Your tests translate with the same compiled locale bundle a release carries. `aircloud i18n bundle` writes it with the platform's own builder: into the site's derived inputs, `app/site/.aircloud/`, when the product has a site, else to `.aircloud/locale-bundle.json`. Both are git-ignored and never uploaded. The generated test layer's `pretest` runs it, so `npm test` needs the `aircloud` CLI installed; run it yourself after you change a locale file or `[i18n]`: ```sh aircloud i18n bundle ``` --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Installing and verifying the CLI The `aircloud` CLI ships for macOS and Linux, on x86-64 and arm64. Windows is not supported. Every channel installs the same signed release. A release is identified by its version (`x.y.z`), and `aircloud version` prints it together with the day it was released and the platform build it was made from (the date is read from the download origin; offline, the version is still printed and the CLI says why the date is not): ```sh aircloud version ``` ## Install with install.sh (recommended) ```sh curl -fsSL https://get.simpleservices.com.br/install.sh | sh ``` The script installs `aircloud` into `~/.local/bin` without `sudo`. Before it installs anything it checks the release: it verifies the signed `latest.json`, verifies the signature over `checksums.txt` with `openssl` against the public key embedded in the script, and then checks the archive's SHA-256 against `checksums.txt`. A mismatch stops the install. To install a specific release instead of the latest, set `AIRCLOUD_VERSION`: ```sh curl -fsSL https://get.simpleservices.com.br/install.sh | AIRCLOUD_VERSION=0.1.12 sh ``` Make sure `~/.local/bin` is on your `PATH`. At the end the script offers to install the AI-Skill for your coding agent: on an interactive terminal it runs `aircloud skill install --detect --prompt`, which asks before each agent it finds. Without a terminal, set `AIRCLOUD_INSTALL_SKILL` to a comma-separated list of agents (for example `claude,codex`) and it runs `aircloud skill install --agent ` for each. See [The AI-Skill](ai-skill.md). ## Homebrew ```sh brew install aircloudhq/tap/aircloud ``` The formula downloads the same archives from `get.simpleservices.com.br`. ## npm ```sh npm install -g @aircloudhq/cli ``` `@aircloudhq/cli` resolves the binary from a per-platform package (`@aircloudhq/cli--`). The npm packages install on Node.js `>=22.0.0`. Node.js only runs the small launcher that starts the native binary, and the install is tested on each Node.js LTS line in that range. On an older Node.js, npm warns `EBADENGINE` and skips the per-platform package, so the install reports success without the binary. `aircloud` then refuses to run: it names your Node.js version and the supported range. Install a Node.js inside the range and run `npm install -g @aircloudhq/cli` again. If you install with `--omit=optional`, npm skips the per-platform package too, and `aircloud` names the package it could not find. Reinstall without that flag. ## Docker The image `ghcr.io/aircloudhq/aircloud` is a multi-arch image whose entrypoint is `aircloud`. It is tagged with each version and `latest`, and signed by digest: ```sh docker pull ghcr.io/aircloudhq/aircloud ``` In a script or CI, pin a version, and mount the product directory as the working directory: ```sh docker run --rm -v "$PWD:/product" -w /product ghcr.io/aircloudhq/aircloud:0.1.12 check ``` A container has no keychain, so a command that calls the platform logs in as a service account (see [Logging in](login.md#service-accounts-ci-and-headless-machines)). Keep the session in a directory of the host through `XDG_CONFIG_HOME`, run as your own user so the files stay yours, and mount the key file read-only at the same path for every run: ```sh docker run --rm --user "$(id -u):$(id -g)" -e XDG_CONFIG_HOME=/state -v "$HOME/.aircloud-ci:/state" \ -v "$HOME/ci-key.json:/keys/ci-key.json:ro" \ ghcr.io/aircloudhq/aircloud:0.1.12 login --service-account /keys/ci-key.json docker run --rm --user "$(id -u):$(id -g)" -e XDG_CONFIG_HOME=/state -v "$HOME/.aircloud-ci:/state" \ -v "$HOME/ci-key.json:/keys/ci-key.json:ro" -v "$PWD:/product" -w /product \ ghcr.io/aircloudhq/aircloud:0.1.12 release create --wait ``` Keep the key file outside the product directory, so it is never committed with the product. ## Upgrading ```sh aircloud changelog aircloud upgrade aircloud upgrade --version 0.1.12 ``` `aircloud changelog` shows where your CLI stands: the latest release, the notes of every newer release — each with the day it was released — and the command that upgrades your install (`--check` exits 1 when a newer release exists). Every release's notes and date are on the [Release notes](../reference/changelog.md) page too, in the main menu. `aircloud upgrade` replaces the binary with the latest release, or with the release `--version` names. The release is verified before it runs: the signed `latest.json`, the signature over `checksums.txt` against the key the running binary embeds, and the checksums of the archive and of the release notes. Any mismatch leaves the binary as it is. After the upgrade it prints what changed — the notes of every release it moved across, newest first, each with the day it was released, with what to do when something you use changed. A release older than the running one is refused unless `--version` names it. A binary that Homebrew or npm installed belongs to that manager, and `aircloud upgrade` tells you to use it instead: `brew update && brew upgrade aircloud` (Homebrew refreshes a tap on its own only once a day, so `brew upgrade` alone can miss a release that just shipped), or `npm install -g @aircloudhq/cli@latest`. On macOS, the first command after an upgrade asks you to log in once more: see [Logging in](login.md#macos-one-new-login-after-each-upgrade). ## What a release contains `get.simpleservices.com.br` serves a signed manifest at its root and each release under `versions//`: | file | what it is | |---|---| | `latest.json`, `latest.json.sig` | the latest version and when it was issued, and its signature | | `versions//checksums.txt` | the SHA-256 of every archive of the release | | `versions//checksums.txt.sig` | the signature over `checksums.txt` (base64 of an ECDSA P-256 signature over its SHA-256) | | `versions//aircloud___.tar.gz` | the archive, `` `darwin` or `linux`, `` `amd64` or `arm64` | | `versions//aircloud___.tar.gz.sbom.json` | the archive's software bill of materials | A published release never changes. ## Verifying a release by hand `install.sh` and `aircloud upgrade` run these checks for you. To run them yourself you need only `openssl` and `shasum`. These are the release public keys, every key version oldest first — the same set `install.sh` and the binary embed. A release is signed with one of them, normally the last: ```text -----BEGIN PUBLIC KEY----- MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgMxKVDQ4N2AJqbEiKoG4sUAelsHR Gmt4z8RgKflPGq9e/rq5ThFvcZ01pG4bOFH/mQYPQf1+YNB3hQXkBp2hsg== -----END PUBLIC KEY----- ``` Save one key, from its `-----BEGIN PUBLIC KEY-----` line to its `-----END PUBLIC KEY-----` line, as `cosign.pub`. Then, for a version and your platform: ```sh V=0.1.12 ARCHIVE=aircloud_${V}_linux_amd64.tar.gz curl -fsSLO https://get.simpleservices.com.br/versions/${V}/checksums.txt curl -fsSLO https://get.simpleservices.com.br/versions/${V}/checksums.txt.sig curl -fsSLO https://get.simpleservices.com.br/versions/${V}/${ARCHIVE} openssl base64 -d -A -in checksums.txt.sig -out checksums.txt.der openssl dgst -sha256 -verify cosign.pub -signature checksums.txt.der checksums.txt grep " ${ARCHIVE}\$" checksums.txt | shasum -a 256 -c ``` `openssl` prints `Verified OK` when the signature holds, and `shasum` prints `: OK` when the archive is the one the signed checksums name; when `openssl` prints `Verification failure`, try the set's other keys before you reject the release. The same two steps verify `latest.json` against `latest.json.sig`. The Docker image is signed by digest, with no transparency-log entry: ```sh cosign verify --key cosign.pub --insecure-ignore-tlog ghcr.io/aircloudhq/aircloud@sha256: ``` ## macOS and Gatekeeper The macOS binaries are not yet notarized. `install.sh` and Homebrew install them without the quarantine attribute, so they run. A binary you download with a browser is quarantined, and Gatekeeper refuses to run it as unidentified: install with `install.sh` or Homebrew instead. --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Logging in Every command that calls the Air-Cloud API acts as the account you logged in to. `aircloud whoami` names it. ## Logging in as a Builder ```sh aircloud login --account acme ``` `aircloud login` opens your browser to authorize the CLI. On a machine without a browser, use the device grant: the CLI prints a URL and a code, and you authorize on any browser. ```sh aircloud login --device ``` `--account` takes the account slug you chose at signup; the CLI remembers the last one in `config.json`. `--region` selects the region whose API to use when your CLI knows several. The first login of a new account asks for the verification code mailed to the address at signup: no token is issued before the address is verified. While it waits for you, the CLI prints the login URL (or the device code and its page) again every 30 seconds. It gives up after five minutes, saying so; `--timeout` sets another wait: ```sh aircloud login --device --timeout 15m ``` A product is authorized separately, the first time a command acts on it: `aircloud release create` does it before its first upload, and `aircloud products authorize ` does it without releasing anything. When a command needs the API and the CLI holds no session, it refuses with `auth.session_missing`; when the session has expired and nothing can renew it, with `auth.session_expired`. Both name the login to run, and neither contacts the platform first (see [Rules and error codes](../reference/errors.md)). `aircloud logout` revokes the cached tokens, deletes the keychain entry, and forgets the session. ## Several accounts on one machine Log in to each account once; each keeps its own session. A product folder names the account and region it belongs to — `aircloud new` and `aircloud products authorize` write `account` and `region` into its `aircloud.toml` — so a command run in that folder acts as that account, with no new login. Outside a product folder, commands act as the selected account: ```sh aircloud accounts list aircloud accounts use acme ``` `aircloud accounts list` shows every logged-in account with its region and marks the selected one with `*`. The first login selects its account; later logins do not change the selection, and say so. Every command that calls the API prints what it acts as on stderr — `aircloud: acting as account acme in lab1` — so a switch is never silent. `AIRCLOUD_TOKEN`, or a service-account login, takes precedence over every account session. ## Where the session lives The CLI keeps one session per account and region: short-lived access tokens, and their expiry, in `~/.config/aircloud/sessions//.json` (or under `$XDG_CONFIG_HOME/aircloud/`), readable only by you. It never writes a long-lived credential there. Logging in to another account, or in another region, leaves every other session intact; the first login selects the account commands act as, and a later one does not change that selection. A service-account login is kept apart, in `service-account.json`. A `session.json` left by an earlier CLI is not read: commands refuse and ask you to run `aircloud logout`, which forgets it, and then to log in again. A Builder login's refresh token is kept only in the operating system's keychain: the macOS Keychain, or the freedesktop Secret Service on Linux (reached over D-Bus). With it the CLI renews its access tokens silently. A session stays usable while you use the CLI at least every two weeks, and asks you to authorize again once a month at the latest. ### Without a keychain When no keychain is reachable — a Linux machine with no D-Bus session, a container, CI — the CLI says so once and keeps the refresh token only in memory, for the command that is running. Nothing long-lived is written, so once the access token expires the next command refuses with `auth.session_expired` and you log in again. For an unattended machine, log in as a service account instead (below). ### macOS: one new login after each upgrade The macOS Keychain ties the refresh token's entry to the binary that wrote it. An upgrade replaces the binary, so the new one cannot read the old entry: it deletes it and asks you to log in once more. No keychain dialog appears. After that one login, renewal is silent again until the next upgrade. ## Service accounts: CI and headless machines A service account is a product's own identity, with a key file instead of a browser login. It is the path for CI and for a headless Linux machine without a keychain. Create it from a Builder login, in the product directory. The CLI generates the key pair and sends only the public key; the private key is written to the file `--out` names, readable by you alone, and never reaches the platform: ```sh aircloud service-accounts create --org-path /ci --scopes tenant:deploy --out ci-key.json ``` `--org-path` is the node the account acts at, at or below yours, and `--scopes` is a subset of your own scopes; a service account can never create another. Every key expires: at `--expires-at` (an RFC 3339 instant) when you give one, else at the platform's ceiling, and the CLI prints the expiry and the account's user id. Copy the key file to the machine, keeping it readable by its owner alone, and log in there: ```sh aircloud login --service-account ci-key.json ``` The CLI reads the key file where it is and never copies it. Before the key expires, register a new one, and retire the old one at once with `--revoke-key`: ```sh aircloud service-accounts rotate --out ci-key-2.json aircloud service-accounts rotate --revoke-key --out ci-key-2.json ``` `aircloud service-accounts list` shows the accounts you may manage — those at or below your node whose scopes you hold — with each one's node, scopes, key expiry and creator. `aircloud service-accounts delete ` revokes an account and every key it holds. --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # The dev MCP server `aircloud mcp` serves a Model Context Protocol server over standard input and output, for your coding agent to launch. `aircloud skill install` registers it with the agent; you never run it by hand. The registration names an absolute path to the `aircloud` that ran the install, so the agent finds it whatever its own `PATH` holds. When your `PATH` finds that same `aircloud` through a package manager's link (Homebrew, npm), the link is what is registered, so an upgrade keeps working; if you install `aircloud` somewhere else, run the install again. ## What it offers Its tools read the product directory and the platform, and run a function. It never writes: creating, generating, releasing and setting secrets stay CLI commands. | tool | what it does | |---|---| | `check` | validates the product directory, as `aircloud check` | | `routes` | the resolved route table, as `aircloud routes` | | `agents_map` | the product's `AGENTS.md` | | `capabilities_list`, `capabilities_diagnostics` | the platform capabilities the product uses, and their diagnostics | | `releases_list`, `release_show` | the product's releases, as `aircloud release list` and `aircloud release show` | | `authz_check` | why a member may or may not act at a node, as `aircloud authz explain`: the decision, the rule and the layer that decided, the membership and its roles there — read with your authority, over the nodes at or below yours ([How authorization works](authorization.md#asking-why)) | | `invocations` | function invocations, as `aircloud logs`, with the same filters (`response_status` included) and the same refusals | | `cli_changelog` | this CLI against the latest signed release, as `aircloud changelog --json`: every newer release's notes and date, and the upgrade command — your agent calls it before writing code | | `feedback_preview`, `feedback_submit` | drafts a platform feedback report and shows exactly what it sends, then sends that report, as `aircloud feedback` | | `function_invoke` | runs a function, as `aircloud functions invoke`, with the request `method`, `path` and `headers` it names — in production unless you name another environment, with your authority: whatever the function does takes effect, and it may be billed | It also serves the product's `AGENTS.md` and the skill's files as resources. Every tool but `function_invoke` and `feedback_submit` is marked read-only; `function_invoke` is marked destructive, open-world and not idempotent, and `feedback_submit` not destructive, not open-world and not idempotent (each call sends a report). The server adds no tool to the agent's auto-approve list, `function_invoke` least of all: your agent asks before running one. ## Whose authority it acts with Each tool call acts with this CLI's session, resolved anew on every call; the server holds no token and no identity of its own, and never starts a login. Log in first with `aircloud login`. With no session, a tool fails and names the command that fixes it. When you hold several memberships in the product, launch it as `aircloud mcp --membership ` to act through one of them ([Members, roles and registration](members.md#memberships-and-their-ids)). ## Headless Linux and CI A machine without a keychain keeps no refresh token (see [Logging in](login.md#without-a-keychain)), so a human login there lasts only as long as its access token. Do not work around that: on such a machine, and in CI, the durable credential is a **service account** of the product. The product's Builder creates the service account and its key file with `aircloud service-accounts create`: the private key never reaches the platform, and every key expires (see [Logging in](login.md#service-accounts-ci-and-headless-machines)). Then, on the machine: ```sh aircloud login --service-account ci-key.json ``` The CLI reads the key file where it is and never copies it, and the MCP server acts with that session. Alternatively, a tenant-scoped bearer token in `AIRCLOUD_TOKEN`, with the API origin in `AIRCLOUD_API`, overrides the session. --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Members, roles and registration Your product's end users are its **members**. A member holds one or more **memberships**, each homed at a node of the product's organization tree (a path such as `/org/customers`) with role keys from your vocabulary. Roles are flat: a route admits a member holding any of the roles it lists, and a member never confers a role it does not hold. How the pieces fit together is [How authorization works](authorization.md). ## Declaring roles and registration Roles and registration are declared once, in `[authenticate]` of `config/routes.toml`: ```toml [authenticate] roles = ["admin", "staff", "customer"] registration = "open" default_roles = ["customer"] default_org_path = "/org/customers" admin_org_path = "/org" ``` | key | what it says | |---|---| | `roles` | the product's role vocabulary; every other role a release names comes from it | | `admin_org_path` | the node of the product's first admin; required with `roles`, refused without | | `registration` | `invite` (the default): only you place end users, through `aircloud members invite`; `open`: anyone may sign up | | `default_roles` | the roles a self-registered end user receives (`open` only) | | `default_org_path` | where a self-registered end user is placed, strictly below `admin_org_path` (`open` only) | | `nodes` | further fixed nodes of the product, for example `nodes = ["/org/staff", { path = "/org/marcas", display_name = "Marcas" }]`: created with their ancestors beside the nodes above, each table entry with its display name; with them, the nodes your routes and triggers may name ([Every node you name is declared](acting-node.md#every-node-you-name-is-declared)) | Each production activation creates `admin_org_path`, `default_org_path`, the `[authenticate.workspaces]` parent and every `nodes` entry when missing. A node you remove from the block is never deleted by a release. An entry's `display_name` is set on its node at each production release, so changing it renames the node; an entry without one leaves the node's name as it is. The posture that counts is the one in the release active in **production**; the product's other environments share it. `aircloud generate authentication` writes this block, the sign-in pages, their session function and the base profiles in `config/profiles.toml` ([Profiles and grants](profiles-and-grants.md)): ```sh aircloud generate authentication aircloud generate authentication --registration open ``` ## The first admin You run nothing to get the first admin. At the first production activation of a release that declares `[authenticate] roles`, the platform invites you, the account owner, as a separate end-user identity, at `admin_org_path`, holding every declared role and the `tenant:org` scope. This happens once. A role you add to the vocabulary later reaches the admin only through `aircloud members update`. A release with an `[authenticate]` block but no `roles` bootstraps nobody. ## Memberships and their ids A **user** is a person: one identity, one sign-in. A **membership** is one place of that person in your product: a home node, the roles held there, the scopes the membership may delegate, and its grants. One person may hold several memberships — a customer account and a company they work for, or staff at two client nodes — and their homes never sit one inside another. Every `aircloud members` command that changes a member addresses the **membership**, by its id, which `aircloud members list` prints beside the user id. To find all of one person's memberships, ask by the user id: ```sh aircloud members list aircloud members memberships 2891… ``` A request acts through one membership. In your product's site, the end user picks it at `/_air/memberships`, without signing in again; a session holding several and none selected is sent there (`session_membership_required` for a request that is not a page). On the CLI you act through your own memberships with `--membership `, needed only when you hold more than one. ## Managing members ```sh aircloud members list --path /staff 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 / aircloud members update 0198a3c4-… --roles staff aircloud members update 0198a3c4-… --path /staff/night --scopes "" aircloud members remove 0198a3c4-… aircloud members remove 0198a3c4-… --block --confirm 0198a3c4-… aircloud members blocks aircloud members unblock ada@example.com ``` - **Invite.** `members invite` places a new membership at a node at or below yours, with the roles you name, the scopes it may delegate (`tenant:org` lets it manage the members below its own node) and, with `--profile`, a non-expiring grant of that profile at its home. You confer only roles and scopes you hold. - **Update.** `members update` changes only what you name: `--roles`, `--scopes`, or `--path`, which **moves** the membership's home. A move is refused while one of the membership's grants, or a group it belongs to, would fall outside the new home (`grant_outside_home`, `group_outside_home`): revoke it first. A member who signed up on their own gets more roles only through a new invite. - **Peers.** A member at your own node is yours to manage only when your roles and scopes there include all of theirs, and never yourself. - **Remove and block.** `members remove` asks you to type the membership id (or takes `--confirm`). `--block` also blocks the member's address from registering again; `members blocks` lists the blocks below your node, and only `members unblock` lifts one. ## Grants, groups and denies A grant confers a profile at a node, optionally until a time; a group shares its grants with every member it holds; a deny refuses roles or operations at and below a node, whatever any grant confers. They are covered in [Profiles and grants](profiles-and-grants.md): ```sh aircloud members grant 0198a3c4-… --path /staff --profile editor --profile-node / --expires-at 2027-01-31T00:00:00Z aircloud members grants 0198a3c4-… aircloud groups add 0198a3c4-… --node /acme --name night-shift aircloud denies create --path /acme --ops entity.delete --entity orders ``` ## Nodes Your clients and their teams are nodes of the tree. You create, archive and delete them from the CLI; a function does the same through the tree operations it declares ([The acting node and elevation](acting-node.md)), and a signed-in end user can create a company of their own when the product declares workspaces ([Workspaces](workspaces.md)). ```sh aircloud org nodes list aircloud org nodes create /acme --name "Acme Ltda" aircloud org nodes rename /acme --name "Acme Comércio Ltda" aircloud org nodes archive /acme aircloud org nodes unarchive /acme aircloud org nodes delete /acme --confirm /acme ``` A node's path is its identity and never changes; its **display name** is what people see — the members page, the NAME column of `org nodes list`. A name has 1 to 100 characters and no line breaks or other control characters (surrounding blanks are trimmed; anything else is refused `org_node_name_invalid`). A workspace's node is named by the name its creator gave it ([Workspaces](workspaces.md)); a node with no name shows its last path segment. A node is always created strictly below yours. **Archive** suspends everything acting at or below the node — sessions, public routes, events, crons and direct invokes — until you unarchive it; nothing is deleted. **Delete** erases an archived node and everything at or below it, once the archive has settled, and cannot be undone. ## Reviewing access ```sh aircloud members review --window 720h aircloud members review --node /acme --window 168h aircloud authz who --node /acme ``` `members review` lists, for a node, the grants expiring within the window, the profiles no grant references, the groups with no member and who holds `tenant:org`. `authz who` lists who reaches a node, with their roles there, and `authz explain` says why one member may or may not act ([How authorization works](authorization.md#asking-why)). ## The members page `aircloud generate members` adds an admin area to the site where your admins manage members themselves, protected by a route role (`admin` by default): ```sh aircloud generate members aircloud generate members --prefix /team --roles admin,staff ``` An admin invites a member at a node picked from a list: the admin's own node, selected by default, and the nodes below it that exist and are not archived — each shown by its display name with its path as a hint, `Acme Ltda (/org/workspaces/acme)`, or by its last path segment when it has no name. The page never makes up a node, so create the nodes your members belong to first (`aircloud org nodes create`, or `[authenticate]` `nodes`, above). The same list is offered for a grant's node and a new group's node. The invite button is disabled while the invite is being sent, so a second click sends nothing. Which records a member can read and write is decided per entity: see [Owner and shared entities](entities.md). --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Profiles, grants, groups and denies A membership's home roles are where its authority starts. Profiles and grants add roles at other nodes, groups share grants among memberships, and denies take roles and operations away. All of them are read on every request ([How authorization works](authorization.md)). ## Profiles A **profile** is a named set of role keys from your `[authenticate] roles` vocabulary. A grant names a profile and never copies its roles, so changing a profile changes the authority of everyone it is granted to. ### Base profiles, in your repository `config/profiles.toml` declares the profiles every node of your product can use: ```toml [profiles.admin] roles = ["admin", "staff", "customer"] [profiles.staff] roles = ["staff"] [profiles.customer] roles = ["customer"] ``` `aircloud generate authentication` writes one profile per role of the vocabulary: the first role's profile (`admin` by convention) holds every role, as your product's first admin does, and each other profile holds its own role. Edit them as your product needs. Every role a profile names must be in the vocabulary (`profile.role_undeclared`). The release active in production carries them: its activation creates or updates them at the root (`/`). A declared profile you remove from the file is deleted when no grant references it; while one does, the profile is kept and the activation reports it, so you revoke those grants first. ### Runtime profiles, at a node ```sh aircloud profiles list aircloud profiles list --node /acme aircloud profiles put --node /acme --name auditor --roles viewer,exporter aircloud profiles remove --node /acme --name auditor ``` A runtime profile is defined at a node below the root and is visible there and at every node below it, never at a sibling or above. Whoever holds `tenant:org` defines profiles at its node or below, holding only roles it holds itself. A profile is removed only once no grant references it. The root holds the declared profiles only: change those in `config/profiles.toml`. ## Grants ```sh aircloud members grant 0198a3c4-… --path /acme/sales --profile editor --profile-node / --expires-at 2027-01-31T00:00:00Z aircloud members grants 0198a3c4-… aircloud members revoke 0198a3c4-… 0198a3c5-… ``` A **grant** confers a profile, named by its node and name (`--profile-node`, `--profile`), to one membership at one node (`--path`), until `--expires-at` or for good. Its node is at or below the membership's home. You grant only profiles whose every role you hold at that node, at a node at or below your own. An expired grant stops counting at its expiry, with nothing to run. `members invite --profile` makes the profile the new membership's non-expiring grant at its home — the way to give a client's admin their roles: ```sh aircloud members invite ada@example.com --path /acme --scopes tenant:org --profile admin --profile-node / ``` **The roles a membership holds at a record's node** are its home roles (when the node is at or below its home), plus the roles of each of its unexpired grants at that node or above, plus the roles of its groups' grants (below), minus every role a deny removes there. A grant at `/acme/sales` therefore reaches the records of `/acme/sales` and below, and nothing at `/acme/ops`. ## Groups ```sh aircloud groups create --node /acme --name night-shift aircloud groups add 0198a3c4-… --node /acme --name night-shift aircloud groups grant --node /acme --name night-shift --path /acme --profile editor --profile-node / aircloud groups list aircloud groups members --node /acme --name night-shift aircloud groups grants --node /acme --name night-shift aircloud groups remove 0198a3c4-… --node /acme --name night-shift aircloud groups revoke 0198a3c5-… --node /acme --name night-shift aircloud groups delete --node /acme --name night-shift ``` A **group** is defined at a node and holds memberships homed at or below that node. Each member holds every role the group's grants confer, at or below both the grant's node and the member's own home — never beyond the home. Adding a member to a group confers the group's roles, so you add one only when you hold every role the group's grants carry. A group is deleted only when it has no member and no grant. ## Denies ```sh aircloud denies create --path /acme --ops entity.delete --entity orders aircloud denies create --path /acme/interns --roles admin aircloud denies list aircloud denies delete 0198a3c6-… ``` A **deny** is a guardrail laid over a node and everything below it. `--roles` removes those roles from everyone acting there; `--ops` refuses those operations (`entity.read`, `entity.create`, `entity.update`, `entity.delete`) on one entity with `--entity`, or on every entity. A deny binds every actor at or below its node — members, group members, functions acting there, elevated aggregates, and you — and no grant, profile, owner rule or `write_roles` below can re-allow what it refuses. A deny is laid strictly below the node of whoever lays it, so a member can never deny a peer at its own node; you, acting at the root, may also deny at `/`. Only someone above the deny's node, or you, lifts it. ## Asking why `aircloud authz explain` names the grant, group, deny or record rule that decided a request, and `aircloud members review` lists the grants about to expire, the profiles nobody uses and the empty groups ([How authorization works](authorization.md#asking-why)). --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Releases and environments A **release** is one version of the whole product — site, functions, containers, schema — built and tested by the platform. An **environment** runs one release at a time. Every product has `production`; other environments are previews, configured together by `config/environments/preview.toml`. ## Creating a release ```sh aircloud release create --wait aircloud release create --dry-run aircloud release create --git https://gitlab.com/me/shop.git --ref main --product shop ``` `release create` uploads the working directory (or, with `--git` and `--ref`, a repository's ref), and the platform builds it and runs its tests. A release moves through `created`, `staged`, `built`, `verifying` and `verified`; it ends `failed` when a step fails, or `superseded` when a newer release overtakes it. `--wait` returns when it is verified, failed or superseded (at most `--timeout`, 30 minutes by default). `--dry-run` validates the upload as the platform would and lists the files it would carry, with their sizes, creating nothing. The first release creates the product on your account. ```sh aircloud release list aircloud release show aircloud release artifacts ``` `release show` gives a release as the platform records it: its status, a table of its parts (when each was queued, started and finished; what a pending part waits on and its place in the build queue; a failed part's error code, message and the last lines of its build log), its test runs, and its activations with what each reported; `--json` prints the whole record as the API returns it. `release create --wait` prints each part's transition as it happens, and a failed part's error code and log tail when the release fails. `release artifacts` lists the test runs' artifacts and downloads them with `--out`. A pending part names what it waits on: `awaiting_dependencies` (the release build has not started it), `queued` (its build is enqueued), `at_capacity:` (with its place in the queue), `building` or `compiling_aot`. ## When your plan cannot pay for a release A release uses part of your plan: the schema changes it applies, its environments, its containers and databases, and the test records it loads. When the platform receives a release, it checks that your plan covers all of it before anything is stored or built. If it does not, `release create` is refused with `release_unfunded`. The CLI lists each missing item, how much the release needs and how much you have (or the limit it would pass). Add credit or move to a plan that covers it, then create the release again. A `--git` release is checked the same way when the platform resolves its source. ## Build capacity An account builds a number of releases at once (`deploy.build.concurrent`) and, within one release, a number of parts at once (`deploy.build.parallelism`); the plan sets both, and the platform can add to them. Every account also shares the platform's build host. A part over one of these waits — `at_capacity:release_concurrency`, `at_capacity:release_parallelism` or `at_capacity:host` — and builds when a slot frees, the longest-waiting first. A wait ends in a refusal only when the builds holding the capacity run past their own deadlines: `build_capacity_exhausted` for the account's capacity (a plan with more build capacity, or an add-on, builds more at once) and `build_capacity_unavailable` for the platform's host (create the release again later). ## Production A verified release is promoted to `production` automatically, when it is newer than the release production runs. To promote by hand instead, declare it in `aircloud.toml`: ```toml [release] promote = "manual" ``` and promote a verified release yourself: ```sh aircloud release promote ``` Only a verified release can run in production. ## Other environments A product has three kinds of environment: - `production`, which every product has from its first release; - the named **previews** you create with `aircloud environments create ` and destroy with `aircloud environments destroy ` ([Environments](environments.md)); none exists until one is created; - `ci-`, which belong to the platform: each is created for one release's verification run and destroyed when that run ends, whatever its verdict. `ci` and every `ci-` name are reserved, so a preview cannot take one. ```sh aircloud release activate --env ``` `release activate` puts a release in a preview that exists; any release whose parts are all built and that has not failed can run there. A name the product has no environment for is refused (`environment_not_found`). ## Rolling back ```sh aircloud release rollback --env production ``` `release rollback` moves an environment back to the release it ran before, or to the one `--to` names. ## Secrets A secret is declared in the product, then its value is set per environment, from standard input — never from an argument, and never shown: ```sh aircloud generate secret STRIPE_KEY --used-by function:checkout aircloud secrets set STRIPE_KEY --env production < key.txt aircloud secrets list ``` `--env ci` sets the value the release's verification run reads: the `ci` scope has its own values, never production's. An activation is refused (`secret_unset`) while a secret its release uses has no value in that environment — the verification run's `ci-` included, so a release whose `ci` scope lacks a declared secret fails verification. A value is set on a product, and the first `aircloud release create` is what creates the product. So the order, for a product that declares a secret before its first release, is: 1. `aircloud release create` — creates the product; its verification fails `secret_unset` for scope `ci`; 2. `aircloud secrets set --env ci` and `aircloud secrets set --env production` for each declared secret; 3. `aircloud release create` again. --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Routes `config/routes.toml` is the product's route table: which path reaches which function or container, and which paths require an end user's session. A route's posture is read off where it is declared, never off an attribute: - a `[[route]]` entry is **public**; - a `[[authenticate.route]]` entry, inside the `[authenticate]` block, **requires a session**. `aircloud routes` prints the resolved table and which routes require a session. ```sh aircloud routes ``` ## Public routes ```toml [[route]] prefix = "/api/health" function = "health" org_path = "/" ``` `prefix` is an absolute path with no trailing slash. A route names exactly one target: `function` or `container` (`flow` and `module` are reserved and refused). `strip_prefix = true` removes the prefix before the request reaches its target. A public route never carries `roles`. A public route has no end user, so a route to a function declares the node its invocations act at, `org_path`: `aircloud check` refuses one without it (`route.org_path_required`). `"/"` acts at the root, over every customer, and counts only because it is written; the generators write it, so edit it to act lower. A route to a container runs no function and declares none (`route.org_path_not_invocation`). See [The acting node and elevation](acting-node.md). ## Public site pages need no route The site is the fallback: every path that no route claims is answered by the site, so a page anyone may open needs no entry in `config/routes.toml`. `/about` is served by the site's `/about` page with nothing declared. A `[[route]]` entry therefore never carries `site`: `aircloud check` refuses it with `schema.unknown_key`, and the message says why. Declare a site route only for pages that require a session, as an `[[authenticate.route]]` with `site = true` (below). ## Routes that require a session ```toml [authenticate] sign_in = "/sign-in" [[authenticate.route]] prefix = "/api/session" function = "session" [[authenticate.route]] site = true prefix = "/account" roles = ["staff"] ``` Without a session, a site page redirects to `sign_in` (by default `/_air/session/login`), and any other request is refused with `session_required`. `roles` narrows a route to the end users holding at least one of the listed roles; a session holding none of them is refused with `session_role_required`. Without `roles`, any session passes. The roles themselves are declared once in `[authenticate]`: see [Members, roles and registration](members.md). The roles are those of the end user's selected membership. `at = ""` evaluates them at that node: the route passes only when one of its roles is effective there or at a node below it, through the membership's home or a grant. A product that declares workspaces must scope with `at` every route admitting a role of its workspace admin profile (`authenticate.route_at_required`, see [Workspaces](workspaces.md)). ## Nested site routes A `site = true` route of `[authenticate]` protects **every path under its prefix**, so one entry protects a whole area of the site. Its page is `src/pages//index.jsx`, named in `src/routes.js` with the path `/*`, and its sub-routes are `` inside that page. With the `/account` route above, `/account/orders/42` requires a session too: it is a sub-route of the `/account` page, never a separate entry. `aircloud check` validates the table against the product, and `aircloud routes` shows it as the platform resolves it. --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e. --- # Using shadcn/ui [shadcn/ui](https://ui.shadcn.com) copies React components into your own source tree, built on Radix primitives and Tailwind. A site created with `aircloud new` is ready for it: the React template uses Tailwind by default, and `@/` already resolves to `src/` in both `vite.config.js` and `jsconfig.json`. This guide takes a site from `shadcn init` to a release that verifies clean, under the product's default Content-Security-Policy. ## Set it up inside the site Run the shadcn CLI in the site directory, `app/site/`, never at the product root: ```sh cd app/site npx shadcn@latest init ``` `init` writes `app/site/components.json`, next to `package.json`. The site admits any top-level `.json` file there as a tooling manifest that the build never reads, so `components.json` needs no exception. Two names are refused: `tsconfig.json` (the site is JavaScript, and `jsconfig.json` already declares its paths) and any `.json` file whose name starts with a dot. Make sure `components.json` carries these values: ```json { "tsx": false, "rsc": false, "tailwind": { "css": "src/styles/application.css" }, "aliases": { "components": "@/components", "ui": "@/components/ui", "utils": "@/lib/utils", "lib": "@/lib", "hooks": "@/hooks" } } ``` - **`tsx: false`.** The site is JavaScript. With `tsx` false, shadcn writes `.jsx` and `.js` files instead of `.tsx` and `.ts`, and resolves the `@/` aliases through `jsconfig.json`. - **`rsc: false`.** A Vite site has no React Server Components. - **`tailwind.css`** is the generated stylesheet, under `app/site/src/styles/`. Every `.css` file in that directory, at any depth, is admitted. - **The aliases.** `@/` is `src/`, so components land under `app/site/src/components/ui/`. Nested directories under `app/site/src/components/` are admitted. The `cn` helper lands in `src/lib/utils.js`: `src/` is open to your own directories, except for its fixed entries (`main.jsx`, `application.jsx`, `routes.js`, `layouts/`, `components/`, `helpers/`, `pages/` and `styles/`). Add components the same way, from `app/site/`: ```sh npx shadcn@latest add dialog aircloud check ``` A component's unit test mirrors its path. For `app/site/src/components/ui/dialog.jsx`, the test goes under `test/site/components/`, in the same `ui/` subdirectory, as `dialog.test.jsx`. ## Remove the CLI once you have scaffolded `shadcn init` can leave the `shadcn` package in the site's dependencies: your stylesheet imports `shadcn/tailwind.css` from it. The running site doesn't need a scaffolding tool. Once the components you need are in place, eject it: ```sh npx shadcn@latest eject ``` `eject` copies the content of `shadcn/tailwind.css` into your stylesheet in place of the import. It then removes `shadcn` from `package.json` with your package manager (`npm uninstall shadcn` for an npm site), which also rewrites `package-lock.json`. On the site this guide was written against, the lockfile went from 460 packages to 168. `eject` asks for confirmation (`--yes` skips it) and cannot be undone: later shadcn updates to that stylesheet no longer apply automatically. If your stylesheet doesn't import `shadcn/tailwind.css`, `eject` reports "Nothing to eject" and changes nothing. In that case, if `shadcn` is still in `package.json`, run `npm uninstall shadcn` yourself. You can keep adding components after ejecting. `npx shadcn@latest add` runs the CLI without making it a dependency. ## The content policy needs no edit A product site runs under the policy in `config/content_security_policy.toml`. Its default `style_src` is `'self'`, which admits no inline style. Radix and sonner create `