Update to FastAPI Cloud

{
  "description": "Prepare and deploy FastAPI apps to FastAPI Cloud. Use when the user asks to deploy a project, create, link, or update a FastAPI Cloud app, log in before deployment, set up CI/CD, a GitHub Actions deploy workflow, or GitHub-linked auto-deploys, manage deploy tokens, validate deployment inputs, inspect app IDs, review `.fastapicloudignore`, or update commands that invoke `fastapi deploy` or `fastapi cloud deploy`.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 196
    }
  ],
  "name": "fastapicloud-deploy",
  "skill_md_contents": "---\nname: fastapicloud-deploy\ndescription: \"Prepare and deploy FastAPI apps to FastAPI Cloud. Use when the user asks to deploy a project, create, link, or update a FastAPI Cloud app, log in before deployment, set up CI/CD, a GitHub Actions deploy workflow, or GitHub-linked auto-deploys, manage deploy tokens, validate deployment inputs, inspect app IDs, review `.fastapicloudignore`, or update commands that invoke `fastapi deploy` or `fastapi cloud deploy`.\"\n---\n\n# FastAPI Cloud Deploy\n\n## Overview\n\nDeploy a local FastAPI project to FastAPI Cloud.\n\n## CLI Baseline\n\nAssume the released project CLI is correct and start with the `fastapi cloud ...` command needed for the task, such as:\n\n```bash\nuv run fastapi cloud deploy --help\n```\n\nOnly check the CLI version after a `uv run fastapi cloud ...` command fails because `fastapi`, `cloud`, or the requested subcommand is missing, or because the output suggests an incompatible CLI:\n\n```bash\nuv run fastapi cloud --version\nuv run fastapi cloud --help\n```\n\nIf `fastapi` is missing or the cloud command surface is stale, install or update `fastapi[standard]`; do not install `fastapi-cli` directly as the executable source. The `fastapi[standard]` extra provides the `fastapi` command and the FastAPI Cloud CLI integration. These commands change project files, so ask the user before running them in an existing project.\n\n```bash\nuv add -U \"fastapi[standard]\"\nuv lock --upgrade-package fastapi --upgrade-package fastapi-cloud-cli\n```\n\nIf there is no project environment, create a temporary uv project and install the same dependency constraints before checking the command surface.\n\nIf the project cloud CLI reports a version older than `0.21.0`, update the project environment before retrying.\n\n## JSON Output\n\nUse `--json` whenever the command supports it. Parse stdout directly as the CLI's structured JSON envelope; treat other stdout as an incompatible or stale command surface.\n\n## Workflow\n\nInspect the project:\n\n```bash\nrg --files -g 'pyproject.toml' -g '.fastapicloud/**' -g '.fastapicloudignore' -g '.gitignore'\nuv run fastapi cloud deploy --help\n```\n\nCheck auth and linked app state:\n\n```bash\nuv run fastapi cloud whoami --json\nuv run fastapi cloud apps get --json\n```\n\nIf auth is missing or stale, ask before starting the login flow. If the project is not linked, inspect apps first; create or link only when the user asks.\n\n## Authentication\n\nPrefer the JSON device flow over plain `login` output:\n\n```bash\nuv run fastapi cloud auth login --no-open --json\n```\n\nSurface the returned `verification_uri_complete` or `verification_uri` plus `user_code` to the user. Then wait with the returned `device_code`:\n\n```bash\nuv run fastapi cloud auth wait --device-code DEVICE_CODE --interval 5 --timeout 300 --json\n```\n\nDeploy only after the user has requested deployment:\n\n```bash\nuv run fastapi cloud deploy . --json\n```\n\nUse `--app-id APP_ID` or `FASTAPI_CLOUD_APP_ID` for a specific target. `--json` deploy output implies non-waiting behavior; for non-JSON deploy commands, use `--no-wait` only when the user wants the command to return before the deployment reaches a terminal state.\n\n## Check Deployment Status\n\nAfter a non-waiting deploy, use the returned deployment ID to check progress:\n\n```bash\nuv run fastapi cloud deployments get DEPLOYMENT_ID --app-id APP_ID --json\n```\n\nInspect `data.deployment.status`. Successful submission is not deployment success. Unless the user requested submission only, continue checking until the deployment reaches a terminal state; report an in-progress status if you cannot establish completion.\n\nWith CLI `0.26.0` or newer, `data.deployment.failure` contains backend build-failure guidance when available: `error_code`, `error_title`, `error_message`, and `error_hint`. Surface the title, message, and any non-empty hint before investigating further. If guidance is absent or more detail is needed, use the `fastapicloud-logs` workflow:\n\n```bash\nuv run fastapi cloud deployments build-logs DEPLOYMENT_ID --no-follow --json\n```\n\nParse stdout even if this command exits with code 1: a failed build can still return a valid JSON result containing logs and failure guidance. Deployment inspection requires a logged-in user session; a CI deploy token alone cannot authenticate these read commands.\n\n## App Creation, Linking, And Updates\n\nUse read commands before write commands:\n\n```bash\nuv run fastapi cloud teams list --json\nuv run fastapi cloud apps list --team-id TEAM_ID --json\nuv run fastapi cloud apps create --team-id TEAM_ID --name APP_NAME --link --path . --json\nuv run fastapi cloud link APP_ID --path . --json\n```\n\nFor a monorepo app, pass `--directory DIRECTORY` to `apps create`. This is the app's relative directory containing `pyproject.toml`; `--path` is the local directory where linking writes configuration.\n\nRead the app before changing its configured directory. `apps update` requires CLI `0.22.0` or newer:\n\n```bash\nuv run fastapi cloud apps get APP_ID --json\nuv run fastapi cloud apps update APP_ID --directory DIRECTORY --json\n```\n\nOnly update app metadata when the user asks. `link` writes `.fastapicloud/cloud.json`; use `--force` only when replacing a known stale link.\n\n## CI And Deploy Tokens\n\nFor non-interactive deploys (CI/CD), authenticate with a deploy token instead of the device flow. These commands require CLI `0.21.0` or newer. Read before mutating:\n\n```bash\nuv run fastapi cloud tokens list --app-id APP_ID --json\n```\n\nCreate or delete tokens only when the user asks. `tokens create` returns the secret value once — write it to a file with `--output-file` or capture it directly into a CI secret; never echo it in chat or shell history. Use `--expires-in-days N` to bound its lifetime:\n\n```bash\nuv run fastapi cloud tokens create --app-id APP_ID --name NAME --output-file PATH --json\nuv run fastapi cloud tokens delete TOKEN_ID --app-id APP_ID --json\n```\n\n### GitHub Actions\n\nPreview the generated workflow first; `print-workflow` is read-only and writes no files or secrets:\n\n```bash\nuv run fastapi cloud ci print-workflow --json\nuv run fastapi cloud ci print-workflow --branch BRANCH\n```\n\n`ci setup` is a mutating convenience: it writes `.github/workflows/deploy.yml` and sets the `FASTAPI_CLOUD_TOKEN` and `FASTAPI_CLOUD_APP_ID` GitHub Actions secrets via the `gh` CLI (creating a deploy token in the process). Run it only when the user asks; first confirm `git` and `gh` are installed and the repo has an `origin` remote, then surface what it will change:\n\n```bash\nuv run fastapi cloud ci setup\n```\n\nFastAPI Cloud also supports native GitHub deployments — linking a repository so pushes deploy automatically. This is not available through the CLI yet; tell the user to set it up from their app's settings in the FastAPI Cloud dashboard.\n\n## Deployment Inputs\n\n- Ensure the project has a `pyproject.toml` with FastAPI dependencies.\n- Inspect `.fastapicloudignore` and `.gitignore` before deploy if large files or secrets may be included.\n- Keep access tokens in environment variables or CI secrets, not source files. App IDs may be passed explicitly with `--app-id` when needed.\n- After deploy, report the deployment ID/status and next diagnostic command if available.\n"
}