Skip to content
Air-Cloud docs

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

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:

aircloud version

Other channels (Homebrew, npm, Docker) and how to verify a release by hand: Installing and verifying the CLI.

2. Install the AI-Skill for your coding agent (optional)

On an interactive terminal the install script offers it. To do it yourself:

aircloud skill install --detect --prompt

This teaches your coding agent the CLI and registers the dev MCP server with it: see The AI-Skill.

3. Create your account

Choose an account slug — lower-case letters, digits and inner hyphens — and sign up with your email address:

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:

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

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:

aircloud whoami

How the session is kept, and what changes on a machine without a keychain: Logging in.

5. Create the product

In an empty directory:

aircloud new shop
cd shop

aircloud new prints a create <path> 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

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

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).

8. Release it

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 <id> (seq 1): <status>, 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 <id> lists its activations. See Releases and environments.

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:

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

aircloud functions invoke hello --data '{"name":"Ada"}'

The response body is printed on standard output:

{"function":"hello","method":"POST"}

and the verdict on standard error: aircloud: ok · response 200 · billed · correlation <id>. 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

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