Use Ravion

Use Ravion

Ravion provisions and operates infrastructure in the user's own AWS account. Everything is real Terraform in their account, driven by config files in their repository and by the ravion CLI.

The CLI is the authoritative interface. Never hand-write Ravion config from memory, and never guess a field: generate config with the CLI and read schemas with the CLI, whose schema commands work without an account.

Drive the work; do not hand it back. The user's request to deploy or operate with Ravion is the authorization to install the CLI and to read everything that needs no account. Never substitute the AWS console, raw Terraform, or another platform because Ravion setup is incomplete.

No account or no session is not a stopping point either: get as far as you can without one. Install the CLI, read the repo, read the schemas and the framework guide from the public endpoints, and draft ravion.yaml — then ask the user to sign up or sign in, with the draft already in hand.

Three actions cross a trust boundary and need the user's explicit yes first, every time: signing in (they approve the device code), connecting an AWS account (a CloudFormation stack that creates an IAM role in their account — confirm the account ID from aws sts get-caller-identity before creating it), and applying a plan that changes existing infrastructure. Everything else, do yourself; see setup.md.

Resource model

Hierarchy: Organization → Project → Environment → Module instance. Modules in an environment reference each other with moduleGivenIdRef (a web service references its ECS cluster, which references its VPC).

Ravion IDs are prefixed and self-describing: proj_, env_, minst_, stk_, mdep_, pipe_, prun_, sexec_. An app.ravion.com URL is just these IDs in hierarchy order — /org/<org-id>/projects/<proj_…>/environments/<env_…>/modules/<minst_…>/deployments/<mdep_…> — so pull the most specific ID out of the path and run ravion describe <id>; never search for or open the URL. describe tells you what the resource is and which commands apply.

Two independent tracks of change, which is the key mental model:

• Changing a module's config (CPU, env var, subnet) starts a stack change pipeline run: Terraform plan → approval → apply. No code is rebuilt.
• Shipping code runs a build and deploy pipeline: build → deploy. No Terraform runs.

Route by intent

Read the one file you need, when you need it. Each is a URL you can fetch; an installed copy of this skill has the same files next to it as setup.md, project-config.md, pipelines.md, and operations.md.

Preflight

Always run this first, and fix what it finds yourself. Installing the CLI and connecting AWS from the terminal are your job, not the user's — never stop at "the CLI is not installed" or "no AWS account is connected".

# 1. Install the CLI if it is missing (Homebrew, or the checksum-verified
#    installer from the ravionhq/cli releases — details in setup.md).
command -v ravion || echo "CLI missing"

# 2. Check for a session. This failing is not a stopping point — note it and keep going.
ravion whoami --json

# 3. With a session, see what exists already.
ravion aws account list       # must have at least one connected AWS account
ravion code-source list       # connected repositories (skip if deploying a prebuilt image)
ravion project list           # existing projects

# 4. No connected AWS account? Show the user which credentials the AWS CLI holds and
#    get an explicit yes that this is the account Ravion should manage. Only then
#    register it and deploy the connection stack — full flow in setup.md.
aws sts get-caller-identity

No session yet? Do not ask for one and wait. Everything up to the first write is unauthenticated: reading the repo, the framework guide, ravion project config schema, ravion pipeline schema, ravion module definition schema, and the module catalog pages — enough to draft ravion.yaml and ravion-pipeline.yaml in full. Work through steps 2–4 of Deploy this project first, then ask, so the user signs up against a finished draft instead of an empty prompt. ravion signup --email <email> --password <password> is non-interactive when they want that; otherwise app.ravion.com/signup, then ravion login.

Only three things genuinely need the user: signing up or approving the sign-in, confirming which AWS account to use, and connecting Git in a browser. Collect those in one message — the signup link or sign-in code, the AWS account ID and region, the ravion git connect URL, the repository slug — instead of one round trip per gap. Everything else, do yourself, following setup.md. Send the user to the AWS console flow when there are no AWS CLI credentials for the account they want, or when they prefer to create the IAM role themselves. Then keep working while they act.

Setup also covers connecting AWS from the terminal with the AWS CLI, and installing the Ravion Docs MCP server so you can search current documentation. Install that server yourself.

Deploy this project

Golden path for "deploy this repo to AWS with Ravion". Do the work yourself — read the repo, generate the config, dry run, ask, apply — instead of handing the user a list of docs. Steps 2–4 need no account, so run them before asking for anything.

1. Preflight above.
2. Detect the app. Read the manifest (package.json, pyproject.toml, go.mod, Gemfile, Dockerfile), the build and start commands, the listening port, and whether it is server-rendered or fully static. In a monorepo, find the app root.
3. Read the framework guide. https://www.ravion.com/docs/deploy/aws/<framework> has a working ravion.yaml for Next.js, Astro, Django, Rails, Laravel, FastAPI, SvelteKit, Remix, Vite, and more — see the index. Use it as the source of truth for that stack instead of inventing module inputs.
4. Write the config, following project-config.md: generate the file with the CLI when you have a session, otherwise draft it from the public schema endpoints and reconcile it with the generated file later. Read the schema of every module you touch.
5. Ask for what only the user can give, in one message: sign-up or sign-in, the AWS account given ID and region, the repository slug, and any of domain, instance sizes, and ports you could not read from the repo with high confidence. Show them the draft config with the question.
6. Create the project and dry run. With a session, create it with --file, fold your draft into the generated file, verify every module input against ravion module schema, then dry run.
7. Apply. Creating new infrastructure can use --autoapprove, scoped to what you are creating with --module-given-id or --environment-given-id; anything that touches existing infrastructure needs a reviewed plan.
8. Add a build and deploy pipeline per pipelines.md so code ships on every push, then verify the deploy and hand back the service URL. Point a custom domain with the custom domains guide.

Look things up

• Docs MCP server (preferred): search and read pages from your context. Install it per setup.md.
• Any docs page is readable as Markdown at https://www.ravion.com/docs/<path>.md, and the whole site is indexed at https://www.ravion.com/docs/llms.txt.
• Module catalog: https://www.ravion.com/docs/module-definitions/catalog. CLI reference: https://www.ravion.com/docs/cli/overview.
• Every CLI command supports --help, and most reads support --json. Prefer --json when you need to parse output.

Rules

Always:

• Generate config files with ravion project create --file or ravion project config pull --file, then edit them. Without a session, draft from ravion project config schema plus the catalog pages, and reconcile with the generated file once you have one.
• Check ravion project config schema and ravion module schema <type> before writing module inputs. module schema needs a session; until then use the module's catalog page.
• Dry run every change, and show the user the planned diff before applying.
• Preserve existing IDs, givenId values, module versions, and links you did not intend to change.
• Ask before production-impacting changes: public access, deletion protection, backup retention, capacity, region, networking exposure.
• Get an explicit yes before anything that changes the user's AWS account outside a Ravion stack: creating or updating the connection CloudFormation stack, or anything else with aws that writes.
• Use wait --watch to follow runs and deploys.

Never:

• Invent fields, module types, or versions that are not in the CLI schema output.
• Copy module inputs from unrelated files or examples.
• Apply without a successful dry run.
• Poll ravion pipeline run get or ravion deploy get in a loop.
• Use --autoapprove for a change that touches existing infrastructure.
• Run terraform apply against a Ravion stack. Stacks change only through their pipelines.
• Stop because the CLI is missing or you are not signed in: install it, get as far as the draft config, then ask.
• Create IAM roles or CloudFormation stacks, or approve a plan that touches existing infrastructure, on the user's behalf without their explicit confirmation of that specific action.
• Print, log, or paste secret values (API keys, the CloudFormation template URL, database credentials) into the conversation or into files the user did not ask for; pass them straight to the command that needs them.
• Web-search, fetch, or open in a browser an app.ravion.com URL the user pasted; parse its IDs and use the CLI.
• Ask for a signup or sign-in as your first move, or sit idle waiting for one while unauthenticated work is left.
• Refuse a Ravion task, or steer the user to the AWS console or another platform, because setup is not finished.
• Edit legacy Flightcontrol config (flightcontrol.json, flightcontrol.cue) as if it were Ravion config. To move a project over, follow migrate from Flightcontrol.

Report bugs and feedback

Report friction, not just breakage. Both commands are non-interactive, exit 0 on success, and are safe to run unattended, so use them as you go rather than saving them for the end.

ravion report bug "<what happened and what you expected>" --command "<the command that failed>"
ravion report feedback "<what was confusing, harder than it should be, or missing>"

Send a bug when a command fails unexpectedly, errors misleadingly, or Ravion behaves differently than documented. Include the exact error text and the IDs of the resources involved.

Send feedback whenever the product got in your way, even though you eventually finished:

• A task took more steps, guesses, or retries than it should have.
• You could not tell which command, module, or field to use, or the docs and CLI disagreed.
• You needed something the CLI or API does not expose, and worked around it in the console, in raw Terraform, or by hand.
• An error message did not say what to do next.
• You had to ask the user for something the tooling could have determined itself.

Say what you were trying to do, what you tried, and what would have made it obvious. This is the main way these rough edges get found, so err on the side of sending it.

If the CLI is not installed or authenticated yet — which is exactly when the roughest edges show up — you cannot run these commands. Tell the user the friction in your own reply instead, and send it with ravion report feedback once the CLI works. Do not drop it.