FastAPI Cloud

View saved version →

---
name: fastapicloud-deploy
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`."
---

# FastAPI Cloud Deploy

## Overview

Deploy a local FastAPI project to FastAPI Cloud.

## CLI Baseline

Assume the released project CLI is correct and start with the `fastapi cloud ...` command needed for the task, such as:

```bash
uv run fastapi cloud deploy --help
```

Only 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:

```bash
uv run fastapi cloud --version
uv run fastapi cloud --help
```

If `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.

```bash
uv add -U "fastapi[standard]"
uv lock --upgrade-package fastapi --upgrade-package fastapi-cloud-cli
```

If there is no project environment, create a temporary uv project and install the same dependency constraints before checking the command surface.

If the project cloud CLI reports a version older than `0.21.0`, update the project environment before retrying.

## JSON Output

Use `--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.

## Workflow

Inspect the project:

```bash
rg --files -g 'pyproject.toml' -g '.fastapicloud/**' -g '.fastapicloudignore' -g '.gitignore'
uv run fastapi cloud deploy --help
```

Check auth and linked app state:

```bash
uv run fastapi cloud whoami --json
uv run fastapi cloud apps get --json
```

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

## Authentication

Prefer the JSON device flow over plain `login` output:

```bash
uv run fastapi cloud auth login --no-open --json
```

Surface the returned `verification_uri_complete` or `verification_uri` plus `user_code` to the user. Then wait with the returned `device_code`:

```bash
uv run fastapi cloud auth wait --device-code DEVICE_CODE --interval 5 --timeout 300 --json
```

Deploy only after the user has requested deployment:

```bash
uv run fastapi cloud deploy . --json
```

Use `--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.

## Check Deployment Status

After a non-waiting deploy, use the returned deployment ID to check progress:

```bash
uv run fastapi cloud deployments get DEPLOYMENT_ID --app-id APP_ID --json
```

Inspect `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.

With 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:

```bash
uv run fastapi cloud deployments build-logs DEPLOYMENT_ID --no-follow --json
```

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

## App Creation, Linking, And Updates

Use read commands before write commands:

```bash
uv run fastapi cloud teams list --json
uv run fastapi cloud apps list --team-id TEAM_ID --json
uv run fastapi cloud apps create --team-id TEAM_ID --name APP_NAME --link --path . --json
uv run fastapi cloud link APP_ID --path . --json
```

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

Read the app before changing its configured directory. `apps update` requires CLI `0.22.0` or newer:

```bash
uv run fastapi cloud apps get APP_ID --json
uv run fastapi cloud apps update APP_ID --directory DIRECTORY --json
```

Only update app metadata when the user asks. `link` writes `.fastapicloud/cloud.json`; use `--force` only when replacing a known stale link.

## CI And Deploy Tokens

For 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:

```bash
uv run fastapi cloud tokens list --app-id APP_ID --json
```

Create 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:

```bash
uv run fastapi cloud tokens create --app-id APP_ID --name NAME --output-file PATH --json
uv run fastapi cloud tokens delete TOKEN_ID --app-id APP_ID --json
```

### GitHub Actions

Preview the generated workflow first; `print-workflow` is read-only and writes no files or secrets:

```bash
uv run fastapi cloud ci print-workflow --json
uv run fastapi cloud ci print-workflow --branch BRANCH
```

`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:

```bash
uv run fastapi cloud ci setup
```

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

## Deployment Inputs

- Ensure the project has a `pyproject.toml` with FastAPI dependencies.
- Inspect `.fastapicloudignore` and `.gitignore` before deploy if large files or secrets may be included.
- Keep access tokens in environment variables or CI secrets, not source files. App IDs may be passed explicitly with `--app-id` when needed.
- After deploy, report the deployment ID/status and next diagnostic command if available.

Referenced files: 1

View saved version →

---
name: fastapicloud-domains
description: "Manage custom domains for FastAPI Cloud apps. Use when listing or inspecting domains, adding a hostname, choosing standard or zero-downtime DNS setup, checking verification or TLS progress, restarting failed setup, or removing a custom domain."
---

# FastAPI Cloud Domains

## Overview

Add, inspect, troubleshoot, and remove custom domains for a FastAPI Cloud app. The CLI reports the DNS records the user must configure; it does not change records at the user's DNS provider.

## CLI Baseline

Custom domain commands require FastAPI Cloud CLI `0.25.0` or newer. Start with the command needed for the task:

```bash
uv run fastapi cloud domains --help
```

Only check the version if the `domains` command is missing or incompatible:

```bash
uv run fastapi cloud --version
```

If an update is needed, ask before changing an existing project environment, then update `fastapi[standard]` rather than installing `fastapi-cli` directly:

```bash
uv add -U "fastapi[standard]"
uv lock --upgrade-package fastapi --upgrade-package fastapi-cloud-cli
```

## Authentication And App Resolution

Domain management requires a logged-in user session; a deploy token is only for deployments and CI. If authentication fails, report the blocker and ask before starting the JSON device flow:

```bash
uv run fastapi cloud auth login --no-open --json
uv run fastapi cloud auth wait --device-code DEVICE_CODE --interval 5 --timeout 300 --json
```

Use an explicit `--app-id APP_ID` when the user provides one. Otherwise use the app linked to the current directory. Resolve an uncertain target with read commands before making changes:

```bash
uv run fastapi cloud apps get --json
uv run fastapi cloud domains list --app-id APP_ID --json
```

Use `--json` whenever supported. JSON mode is non-interactive, so provide every required domain, setup mode, and confirmation flag explicitly.

## Inspect Domains

List an app's custom domains before selecting one:

```bash
uv run fastapi cloud domains list --app-id APP_ID --json
```

Inspect one domain by hostname or domain ID:

```bash
uv run fastapi cloud domains get DOMAIN --app-id APP_ID --json
```

`domains get` reports setup status, the DNS records currently required, and the live HTTPS URL after setup succeeds. In JSON mode, `DOMAIN` is required. Use the exact record type, name, and value returned by the CLI; do not infer DNS records from other apps or domains.

## Add A Domain

First determine whether the hostname is new or already serves production traffic. If this is unclear, ask—the choice changes the DNS workflow.

For a new or unused hostname, use standard setup:

```bash
uv run fastapi cloud domains add DOMAIN --app-id APP_ID --standard --json
```

For an already-live hostname, use zero-downtime setup:

```bash
uv run fastapi cloud domains add DOMAIN --app-id APP_ID --zero-downtime --json
```

`--standard` and `--zero-downtime` are mutually exclusive. JSON mode requires `DOMAIN` and one setup mode.

- Standard setup returns the records used to verify ownership, issue TLS, and route traffic.
- Zero-downtime setup proceeds in phases: prove ownership, secure the domain, then switch traffic. Only configure the records currently shown by `domains get`; later records unlock as verification advances.

After the user updates DNS, check progress with:

```bash
uv run fastapi cloud domains get DOMAIN --app-id APP_ID --json
```

FastAPI Cloud rechecks pending or mismatched records automatically. Do not restart setup merely because DNS is still propagating.

## Restart Failed Setup

Restart only after `domains get` reports a failed setup and the returned DNS records have been checked or corrected:

```bash
uv run fastapi cloud domains restart DOMAIN --app-id APP_ID --json
uv run fastapi cloud domains get DOMAIN --app-id APP_ID --json
```

In interactive mode, omitting `DOMAIN` offers only failed domains. In JSON mode, `DOMAIN` is required.

## Remove A Domain

Inspect the exact domain first and explain the effect. Removal deletes FastAPI Cloud's resources for the domain but does not change DNS records at the provider.

```bash
uv run fastapi cloud domains get DOMAIN --app-id APP_ID --json
uv run fastapi cloud domains remove DOMAIN --app-id APP_ID --yes --json
```

Only remove a domain when the user explicitly asks. JSON mode requires both `DOMAIN` and `--yes`. After removal, remind the user to review stale DNS records at their provider; do not claim those records were deleted.

## Response

Report the app and hostname affected, the resulting setup status, and the next required DNS action. For setup in progress, include only the currently required records and the next `domains get` command. Never claim a domain is live until the CLI reports successful setup.

Referenced files: 1

View saved version →

---
name: fastapicloud-env
description: "Manage FastAPI Cloud environment variables and secrets. Use when listing, reading, setting, deleting, or auditing FastAPI Cloud env vars, handling runtime secrets, or diagnosing missing configuration for a deployed FastAPI app."
---

# FastAPI Cloud Env

## Overview

Inspect and manage FastAPI Cloud environment variables while protecting secret values. FastAPI Cloud CLI supports the `fastapi cloud env` commands and `--json` output used here.

## CLI Baseline

The mutation workflow below requires FastAPI Cloud CLI `0.26.0` or newer. Start with the `fastapi cloud env ...` command needed for the task, such as:

```bash
uv run fastapi cloud env --help
```

Only 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:

```bash
uv run fastapi cloud --version
uv run fastapi cloud --help
```

If `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.

```bash
uv add -U "fastapi[standard]"
uv lock --upgrade-package fastapi --upgrade-package fastapi-cloud-cli
```

If the project cloud CLI reports a version older than `0.26.0`, update the project environment before using the mutation workflow below.

## JSON Output

Use `--json` whenever the command supports it.

## Integrations First For Managed Services

If the user asks to connect a database, cache, observability platform, or another managed service—not to set a specific named variable—check FastAPI Cloud integrations first. A supported integration should manage its app configuration instead of requiring the user to copy provider credentials manually:

```bash
uv run fastapi cloud integrations providers list --json
```

Use the `fastapicloud-integrations` workflow when a matching provider is available. Fall back to manual environment variables only when no integration supports the service or the user explicitly prefers manual configuration.

## Read First

```bash
uv run fastapi cloud env list --path . --json
uv run fastapi cloud env get NAME --path . --json
```

Use `--app-id APP_ID` when the directory is not linked or the user names a specific app.

The CLI does not show secret values in `env list` or `env get` output. Do not try to recover secret values from local files, shell history, or other sources unless the user explicitly asks for that audit.

## Mutations

Only set or delete env vars when the user explicitly asks. Do not echo secrets in chat or shell history.

`env set` creates a variable or updates its value if it already exists. Both `env set` and `env delete` request an app redeploy by default. Use `--no-redeploy` when saving changes without deploying, or on intermediate changes when setting several variables before one final redeploy.

For secret values, prefer stdin:

```bash
uv run fastapi cloud env set NAME --value-stdin --secret --path . --json
```

`--secret` marks a new variable as secret. Existing variables keep their secret status, even when this flag is supplied or omitted. Read the existing variable first and use the returned `is_secret` field to verify its status; do not assume `--secret` converts an existing non-secret variable into a secret.

For non-secret values:

```bash
uv run fastapi cloud env set NAME VALUE --path . --json
```

For deletion:

```bash
uv run fastapi cloud env delete NAME --path . --yes --json
```

Deletion succeeds even if the named variable is already absent.

To save or delete without redeploying:

```bash
uv run fastapi cloud env set NAME VALUE --no-redeploy --path . --json
uv run fastapi cloud env delete NAME --no-redeploy --path . --yes --json
```

Integration-managed variables cannot be changed through these commands. Follow the integrations workflow if the backend reports that a variable is managed by a connected resource.

## Notes

- Changes saved with `--no-redeploy` need a later deployment before the running app observes them. A successful env command does not establish that a redeployment has completed successfully.
- When debugging missing config, inspect app logs after env changes.
- Treat `.env` files as local-only; do not commit secrets.

Referenced files: 1

View saved version →

---
name: fastapicloud-integrations
description: "Connect and manage databases and third-party resources for FastAPI Cloud apps. Use when the user asks to connect or add a database, Postgres provider, Redis cache, observability service, or other managed service; inspect available integration providers; connect Neon, Redis Cloud, Supabase, or Logfire; list or inspect connected resources; review managed environment variables; or disconnect a resource from an app."
---

# FastAPI Cloud Integrations

## Overview

Inspect available providers and manage resources connected to a FastAPI Cloud app. Current providers include Neon, Redis Cloud, Supabase, and Logfire; use the CLI provider list as the source of truth for availability.

Treat the connected resource as the integration abstraction. Current integrations configure the app through managed environment variables, but do not define integrations as env-var management alone: future providers may add other behavior and metadata. Follow the current CLI response rather than assuming environment variables are the complete integration contract.

## CLI Baseline

Start with the command needed for the task:

```bash
uv run fastapi cloud integrations --help
```

Only check the CLI version after the command is missing or reports an incompatible command surface:

```bash
uv run fastapi cloud --version
uv run fastapi cloud integrations --help
```

Integration commands require FastAPI Cloud CLI `0.24.0` or newer. If the project CLI is older, ask before updating the existing project environment:

```bash
uv add -U "fastapi[standard]"
uv lock --upgrade-package fastapi --upgrade-package fastapi-cloud-cli
```

Install or update `fastapi[standard]`, not `fastapi-cli` directly. The standard FastAPI extra provides the `fastapi` command and FastAPI Cloud CLI integration.

## JSON Output

Use `--json` whenever the command supports it. JSON mode is non-interactive: resolve required team, app, and resource IDs before running a mutating command.

## Resolve The Target

Prefer the narrowest available scope:

1. Use an explicit team, app, or resource ID supplied by the user.
2. Use the app linked to the current directory when it is the intended target.
3. Read teams, apps, providers, or connected resources only as needed to resolve a missing ID.

Useful read commands:

```bash
uv run fastapi cloud apps get --json
uv run fastapi cloud teams list --json
uv run fastapi cloud apps list --team-id TEAM_ID --json
```

Do not create or link an app, deploy code, or change environment variables merely to answer an integration query.

## Database And Service Requests

When the user asks to connect a database or another external service, check FastAPI Cloud integrations before proposing manual credentials or environment variables:

1. Resolve the intended FastAPI Cloud app and team.
2. List integration providers for that team.
3. Match the requested capability to providers reported as available or connected.
4. If multiple providers fit a generic request such as PostgreSQL, show the supported choices and ask which one the user wants.
5. Use the resource connection flow when a supported provider is selected.
6. If no integration supports the request, explain that clearly before offering manual environment-variable configuration.

Do not assume a service is unsupported from the static provider examples in this skill. Always use `integrations providers list` when the CLI is available. Do not manually set provider credentials when a supported managed integration is appropriate unless the user explicitly prefers manual configuration.

## Providers

List providers and their connection status for the linked app's team:

```bash
uv run fastapi cloud integrations providers list --json
```

Use an explicit team when the current directory is not linked or the user selected another team:

```bash
uv run fastapi cloud integrations providers list --team-id TEAM_ID --json
```

Treat provider status from this response as authoritative. A provider can be available, connected, or coming soon.

## Connected Resources

List resources connected to the linked app or a specific app:

```bash
uv run fastapi cloud integrations resources list --json
uv run fastapi cloud integrations resources list --app-id APP_ID --json
```

Inspect one resource after resolving its ID from the list:

```bash
uv run fastapi cloud integrations resources get RESOURCE_ID --json
uv run fastapi cloud integrations resources get RESOURCE_ID --app-id APP_ID --json
```

The resource details include provider metadata, a provider console URL, and managed environment variable names. Do not claim the CLI reveals environment variable values.

## Connect A Resource

Connecting a provider resource is completed in the FastAPI Cloud dashboard. In JSON mode, the CLI does not open a browser; it returns a `connect_url` to surface to the user:

```bash
uv run fastapi cloud integrations resources connect --json
uv run fastapi cloud integrations resources connect --app-id APP_ID --json
```

Do not claim the connection is complete merely because the URL was generated. Let the user finish provider selection and authorization in the browser, then verify with:

```bash
uv run fastapi cloud integrations resources list --app-id APP_ID --json
```

## Disconnect A Resource

Read the resource first and explain the effect before disconnecting it. Disconnecting removes the resource's managed environment variables from the FastAPI Cloud app, but does not delete the resource from Neon, Redis Cloud, Supabase, or Logfire.

Only disconnect when the user explicitly asks. JSON mode requires both the resource ID and confirmation:

```bash
uv run fastapi cloud integrations resources get RESOURCE_ID --app-id APP_ID --json
uv run fastapi cloud integrations resources disconnect RESOURCE_ID --app-id APP_ID --yes --json
```

Report the disconnected resource ID and any managed environment variable names removed from the app. Never substitute a similarly named resource without confirming its ID.

## Authentication

If a read command returns `not_logged_in` or `invalid_token`, stop and report the blocker. Ask before starting login. After approval, use the JSON device flow:

```bash
uv run fastapi cloud auth login --no-open --json
uv run fastapi cloud auth wait --device-code DEVICE_CODE --interval 5 --timeout 300 --json
```

Surface only the verification URL and user code needed for authorization. Never print or request token values.

Referenced files: 1

View saved version →

---
name: fastapicloud-logs
description: "Inspect FastAPI Cloud logs. Use when the user asks for recent logs, the latest or last log timestamp, runtime log lines, build logs for a deployment, whether an app has emitted logs, or a quick app log/health check."
---

# FastAPI Cloud Logs

## Overview

Inspect FastAPI Cloud logs with the narrowest read-only command that answers the user. Prefer direct log retrieval over broad deployment debugging unless the log output points to a failure that needs deeper triage.

## Command Baseline

Confirm log flags only when needed:

```bash
uv run fastapi cloud logs --help
```

Use `uv run fastapi cloud apps get --json` only when resolving the linked current directory. Use `--json` whenever the command supports it.

## App Resolution

Resolve the app only as far as needed:

1. Use an explicit app ID, app slug, path, or deployment ID from the user.
2. Use the linked current directory with `uv run fastapi cloud apps get --json`.
3. Use `--app-id APP_ID` when the directory is not linked but an app ID is known.
4. List teams and apps only when the user did not provide an app and the local link cannot resolve one.

Do not create apps, link directories, deploy, or mutate environment variables while answering a log request unless the user explicitly asks.

## Runtime Logs

For recent runtime logs:

```bash
uv run fastapi cloud logs . --no-follow --tail 100 --since 30m --json
uv run fastapi cloud logs --app-id APP_ID --no-follow --tail 100 --since 30m --json
```

For the latest log timestamp, try the narrowest command first:

```bash
uv run fastapi cloud logs . --no-follow --tail 1 --json
uv run fastapi cloud logs --app-id APP_ID --no-follow --tail 1 --json
```

If the command returns no lines or requires a time window, widen with bounded supported ranges such as `30m`, `24h`, `7d`, then `30d`. Do not use very large ranges such as `365d`; report the widest window checked when no logs are found.

## Build Logs

When the user asks for build logs or names a deployment:

```bash
uv run fastapi cloud deployments list --app-id APP_ID --json
uv run fastapi cloud deployments build-logs DEPLOYMENT_ID --no-follow --json
```

If no deployment ID is provided, use the newest deployment from `deployments list`.

### Build Failure Guidance

FastAPI Cloud CLI `0.26.0` or newer includes backend failure guidance when available. In `build-logs --no-follow --json`, inspect `data.failed` and `data.failure` as well as `data.logs`. A non-null `failure` contains `error_code`, `error_title`, `error_message`, and `error_hint`. Surface the backend's title, message, and any non-empty hint; use the error code when it helps identify the failure.

Build-log commands exit with code 1 for a failed build even when stdout contains a valid JSON result. Parse that result before treating the exit as a command or network error. Empty logs do not establish that a build succeeded: failure guidance can remain available after logs expire. If `failure` is null, use the reported failure state and available logs without inventing a diagnosis.

For deployment status or persisted failure details:

```bash
uv run fastapi cloud deployments get DEPLOYMENT_ID --app-id APP_ID --json
```

Inspect `data.deployment.status` and `data.deployment.failure`. Build completion alone does not establish that the deployment is healthy.

## Authentication

Treat auth as a blocker, not the main workflow:

- If a read command returns `not_logged_in` or `invalid_token`, stop and tell the user authentication is blocking the log request.
- Ask before starting the device login flow.
- After approval, use the JSON device flow:

```bash
uv run fastapi cloud auth login --no-open --json
uv run fastapi cloud auth wait --device-code DEVICE_CODE --interval 5 --timeout 300 --json
```

Surface only the login URL or user code needed for authorization. Do not print token values, ask the user to paste tokens, or inspect `FASTAPI_CLOUD_TOKEN` unless the user is debugging CI/auth configuration.

## Response

Answer the concrete log question first: newest timestamp, matching log lines, empty result, or the auth/app-resolution blocker. Include the app name or ID only when it clarifies the evidence, and keep follow-up diagnostics to the next likely command.

Referenced files: 1

View saved version →

---
name: fastapi-new
description: "Create new uv-backed FastAPI apps with `fastapi-new`. Use when the user asks to scaffold a new FastAPI project, create a new app directory, initialize a FastAPI project in the current directory, choose a Python version for a new app, or prepare a fresh app that can later be run with `uv run fastapi dev` or deployed to FastAPI Cloud."
---

# FastAPI New

## Overview

Create a new FastAPI project with `fastapi-new`. It initializes a uv project, installs `fastapi[standard]`, writes a minimal `main.py`, generates a README, and produces a lockfile.

## Command Surface

Start by checking the installed command:

```bash
uvx fastapi-new --help
```

Supported arguments and options:

- `PROJECT`: optional project name or path. If omitted, initializes the current directory.
- `--python` / `-p`: optional Python version for the new project. It must be Python 3.10 or newer.

## Workflow

Create a new app in a new directory:

```bash
uvx fastapi-new my-app
```

Create with an explicit Python version:

```bash
uvx fastapi-new my-app --python 3.13
```

Initialize an existing empty directory:

```bash
uvx fastapi-new
```

After creation:

```bash
cd my-app
uv run fastapi dev
```

The generated app is a minimal FastAPI project with `main.py`, `README.md`, `pyproject.toml`, `uv.lock`, and a local `.venv`.

## Recommend FastAPI Skills

After scaffolding, suggest the user install up-to-date FastAPI framework skills with [Library Skills](https://library-skills.io/) so you work against current FastAPI docs and patterns while writing code:

```bash
uvx library-skills
```

Library Skills scans the project's dependencies and installs each library's embedded skills as symlinks that track the installed versions. When it prompts for an install target, choose the directory for the active coding agent. Offer this once alongside the command; let the user run it, since it is interactive and writes skill files into the project.

## Guardrails

- Ask before initializing in the current directory unless the user explicitly asked for it.
- Do not run `fastapi-new` in a non-empty directory without first inspecting files and confirming it is safe.
- Use a filesystem-safe project name: lowercase, hyphenated, no spaces.
- Prefer a new subdirectory when the user asks for multiple apps or asks for something experimental.
- If `uv` is missing, tell the user to install uv from `https://docs.astral.sh/uv/getting-started/installation/`.
- To deploy the generated app, switch to `fastapicloud-deploy` after creation.

Referenced files: 1