Update to Cargo CLI

{
  "name": "cargo-hosting",
  "description": "Put something on the internet from Cargo — Vite single-page apps served at https://<slug>.cargo.app and serverless edge workers that answer HTTP requests, plus the deployments that build and promote them. Triggers: \"build me a dashboard for this\", \"host this app\", \"give me a URL to share\", \"deploy this\", \"I need a webhook endpoint\", \"make it live\", \"promote to production\", \"put it on cargo.app\", \"ship a UI for my team\". Skip when: the app or worker should be declared as committed workspace code — use cargo-cdk.",
  "included_files": [
    {
      "relative_path": "references/examples/apps.md",
      "size_in_bytes": 3246
    },
    {
      "relative_path": "references/examples/deployments.md",
      "size_in_bytes": 2276
    },
    {
      "relative_path": "references/examples/workers.md",
      "size_in_bytes": 2819
    },
    {
      "relative_path": "references/response-shapes.md",
      "size_in_bytes": 3892
    },
    {
      "relative_path": "references/troubleshooting.md",
      "size_in_bytes": 3296
    },
    {
      "relative_path": "skill-metadata.json",
      "size_in_bytes": 1035
    }
  ],
  "skill_md_contents": "---\nname: cargo-hosting\ndescription: \"Put something on the internet from Cargo — Vite single-page apps served at https://<slug>.cargo.app and serverless edge workers that answer HTTP requests, plus the deployments that build and promote them. Triggers: \\\"build me a dashboard for this\\\", \\\"host this app\\\", \\\"give me a URL to share\\\", \\\"deploy this\\\", \\\"I need a webhook endpoint\\\", \\\"make it live\\\", \\\"promote to production\\\", \\\"put it on cargo.app\\\", \\\"ship a UI for my team\\\". Skip when: the app or worker should be declared as committed workspace code — use cargo-cdk.\"\nversion: \"1.0.1\"\ncompatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token\nhomepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Hosting\n\n**Cargo Hosting** runs two kinds of workspace-scoped resources, plus the deployments that ship them:\n\n- **App** — a Vite single-page app served on `https://<slug>.cargo.app`, built on `@cargo-ai/app-sdk` (Vite + refine + shadcn primitives, with `getCargoEnv()` / `useCargoApi()` wired to the workspace).\n- **Worker** — a serverless HTTP handler that runs on the edge (`fetch(request, env)`), built on `@cargo-ai/worker-sdk` (auto OpenAPI 3.1 spec at `/openapi.json`, Swagger UI at `/docs`).\n- **Deployment** — one build+upload of a local source directory to an app or worker. A deployment is **not live until it's promoted**.\n\n> For organizing apps/workers into **folders**, use [`cargo-workspace-management`](../cargo-workspace-management/SKILL.md) (`folder …`). The `--folder-uuid` flags here consume those folder UUIDs.\n\n> See `references/examples/apps.md`, `references/examples/workers.md`, and `references/examples/deployments.md` for end-to-end walkthroughs.\n> See `references/response-shapes.md` for JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use\n                                        # alternatives: --oauth (browser) · --token <api-token> (CI)\ncargo-ai whoami                         # confirm the active workspace before any write\n```\n\nEvery command prints JSON to stdout; failures exit non-zero with `{\"errorMessage\": \"...\"}`. Anything that creates a run or a batch is async — pass `--wait-until-finished` or poll the matching `get`. When the full skill bundle is installed, [`../cargo/references/prerequisites.md`](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin-only surface.\n\n## The lifecycle\n\nApps and workers follow the same shape — **scaffold → create slot → deploy → promote**:\n\n```\ninit (local scaffold) → create (slot + slug) → deployment create (build+upload) → deployment promote (go live)\n```\n\n1. **Scaffold** a local project from a template — `hosting app init <dir>` / `hosting worker init <dir>`.\n2. **Create the slot** in the workspace — `hosting app create --name --slug` → `appUuid` (or `workerUuid`). The `--slug` becomes the subdomain and **must be globally unique within the hosting domain**.\n3. **(apps, optional) Wire local dev** — `hosting app env <appUuid>` prints the `.env.local` lines a local copy needs (Cargo OAuth + workspace + app UUID + API URL).\n4. **Deploy** — `hosting deployment create --app-uuid <uuid> --source <dir>` uploads the source; the backend runs `npm ci && vite build` (apps) or bundles the entrypoint (workers) in a sandbox. Returns a `deploymentUuid`.\n5. **Promote** — `hosting deployment promote --uuid <deploymentUuid>` points the live URL at that build.\n\nDeploys build asynchronously — **poll `hosting deployment get <uuid>`** until the status is terminal before promoting (see [Async polling](#async-polling)).\n\n## Apps\n\n```bash\n# Discover\ncargo-ai hosting app list                          # all apps (filter with --folder-uuid <uuid>)\ncargo-ai hosting app get <uuid>                     # one app's details + URL\n\n# Scaffold locally (Vite + @cargo-ai/app-sdk)\ncargo-ai hosting app init ./my-app --list-templates # see available templates, then:\ncargo-ai hosting app init ./my-app --template blank --name \"My App\"\n\n# Create the slot (slug must be globally unique → it's the subdomain)\ncargo-ai hosting app create --name \"My App\" --slug my-app --folder-uuid <folder-uuid>\n\n# Print .env.local for local development\ncargo-ai hosting app env <app-uuid>\ncargo-ai hosting app env <app-uuid> --api-url https://api.getcargo.io\n\n# Update / remove\ncargo-ai hosting app update --uuid <app-uuid> --name \"Renamed\"\ncargo-ai hosting app update --uuid <app-uuid> --folder-uuid null   # move to workspace root\ncargo-ai hosting app remove <app-uuid>                             # also removes its deployments\n```\n\nTemplates: `blank` (minimal starting point) and `territories-overview` (read-only territories grid demoing `useCargoApi()` + react-query). Run `app init <dir> --list-templates` for the current list.\n\n## Workers\n\nSame command shape as apps — substitute `worker` for `app`:\n\n```bash\ncargo-ai hosting worker list                        # filter with --folder-uuid <uuid>\ncargo-ai hosting worker get <uuid>\n\n# Scaffold (edge fetch(request, env) handler on @cargo-ai/worker-sdk)\ncargo-ai hosting worker init ./my-worker --list-templates\ncargo-ai hosting worker init ./my-worker --template blank --name \"My Worker\"\n\ncargo-ai hosting worker create --name \"My Worker\" --slug my-worker --folder-uuid <folder-uuid>\ncargo-ai hosting worker update --uuid <worker-uuid> --name \"Renamed\"\ncargo-ai hosting worker remove <worker-uuid>        # also removes its deployments\n```\n\nTemplates: `blank` (auto OpenAPI spec + Swagger UI) and `custom-integration` (a Cargo Custom Integration — manifest / actions / extractors / autocompletes / dynamic schemas). Workers have **no `env` subcommand** — they read config from the `env` argument passed to `fetch` at runtime.\n\n## Deployments\n\nA deployment belongs to exactly one app **or** one worker (`--app-uuid` and `--worker-uuid` are mutually exclusive).\n\n```bash\n# List / inspect\ncargo-ai hosting deployment list --app-uuid <uuid>          # or --worker-uuid <uuid>\ncargo-ai hosting deployment get <deployment-uuid>           # status + metadata\ncargo-ai hosting deployment get-promoted --app-uuid <uuid>  # what's currently live\n\n# Build & upload a local source directory (point at the package root, NOT dist/)\ncargo-ai hosting deployment create --app-uuid <uuid> --source ./my-app\ncargo-ai hosting deployment create --worker-uuid <uuid> --source ./my-worker\n# default ignores: node_modules,dist,build,.git,.next — override with --ignore \"a,b,c\"\n\n# Go live\ncargo-ai hosting deployment promote --uuid <deployment-uuid>\n```\n\n## Critical rules\n\n- **`--slug` must be globally unique within the hosting domain** — it's the live subdomain (`<slug>.cargo.app`). A clash fails at `create`.\n- **Deploying ≠ going live.** `deployment create` builds and uploads; the URL only changes when you `deployment promote` that deployment. Use `deployment get-promoted` to see what's live now.\n- **`--source` is the package root, not `dist/`.** The build runs in a Cargo sandbox: `npm ci && vite build` for apps, entrypoint bundling for workers. Shipping a pre-built `dist/` will not work.\n- **Builds are async** — poll `deployment get` until terminal before promoting (see below).\n- **`--app-uuid` / `--worker-uuid` are mutually exclusive** on `deployment create`, `deployment list`, and `deployment get-promoted`. Pass exactly one.\n- **`remove` cascades** — removing an app or worker also removes all of its deployments.\n- **`update --folder-uuid null`** (literal string `null`) moves a resource back to the workspace root.\n- **Hosting consumes credits monthly per resource.** Each app/worker carries a `chargedUntil` that an hourly sweep advances a month at a time, so a live app or worker bills hosting credits on an ongoing basis — `remove` resources you no longer serve. Track consumption via [`cargo-billing`](../cargo-billing/SKILL.md).\n\n## Async polling\n\n`deployment create` kicks off a sandboxed build. The deployment's `status` moves `pending → building → success` (or `error` / `cancelled`). Poll until terminal, then promote the `success` one:\n\n```bash\ncargo-ai hosting deployment get <deployment-uuid>   # poll ~2–5s until status is terminal\n```\n\nTerminal statuses are `success`, `error`, and `cancelled` — only promote a `success` deployment. On `error`, read the deployment's `errorMessage` (and `buildLogS3Filename`) to diagnose the build. For the general polling pattern (intervals, retries), see [`../cargo-orchestration/references/polling.md`](../cargo-orchestration/references/polling.md).\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai hosting app create --help\ncargo-ai hosting deployment create --help\n```\n"
}