mirror of https://github.com/getcargohq/cargo-skills.git synced 2026-09-14 19:17:15 +08:00

Files

T

Auree Aubert 53a1a86a7f Add cargo-hosting skill for app and worker deployment (#40 )

* Add cargo-hosting capability skill

Document the `hosting` CLI domain (apps, workers, deployments) as a
dedicated capability skill, following the one-skill-per-CLI-domain
convention.

- cargo-hosting/SKILL.md: init -> create -> deploy -> promote lifecycle
  for Vite SPA apps (*.cargo.app) and edge workers, with critical rules
  and async polling.
- references/examples/{apps,workers,deployments}.md, response-shapes.md,
  troubleshooting.md.
- Register in the cargo router (skill count 10->11, capability table row,
  recap, removed hosting from the no-skill-yet table, synced frontmatter
  count) and bump cargo 1.4.0 -> 1.5.0.
- README capability table + skill count (11 -> 12).
- CHANGELOG entries for cargo-hosting 1.0.0 and cargo 1.5.0.

https://claude.ai/code/session_018LeD9abpD7LYBhGGkDxSup

* Add hosting terms to glossary

Add app/appUuid, deployment/deploymentUuid, hosting, worker/workerUuid
entries to cargo/references/glossary.md, and correct the capability-skill
domain list (was missing content and hosting). CHANGELOG updated.

https://claude.ai/code/session_018LeD9abpD7LYBhGGkDxSup

* Pin hosting response shapes from backend types

Replace inferred shapes/caveats in cargo-hosting with the authoritative
App/Worker/Deployment structures: kind app/worker discriminant,
promotedDeployment, chargedUntil, and the deployment status enum
(pending/building/success/error/cancelled, terminal at the last three).
Polling + build-failure docs now cite the real status/errorMessage/
buildLogS3Filename fields, and a critical rule notes monthly hosting
credits per resource.

https://claude.ai/code/session_018LeD9abpD7LYBhGGkDxSup

---------

Co-authored-by: Claude <noreply@anthropic.com>

2026-06-15 10:30:32 +02:00

3.2 KiB

Raw Permalink Blame History

App examples

Apps are Vite single-page apps served on https://<slug>.cargo.app, scaffolded from @cargo-ai/app-sdk.

Scaffold → create → deploy → promote (end to end)

# 1. See what templates exist, then scaffold a local project
cargo-ai hosting app init ./territories --list-templates
cargo-ai hosting app init ./territories --template territories-overview --name "Territories"

# 2. Create the workspace slot. --slug is the live subdomain → must be globally unique.
cargo-ai hosting app create --name "Territories" --slug territories
# → { "uuid": "<app-uuid>", "slug": "territories", "url": "https://territories.cargo.app", ... }

# 3. (optional) Develop locally — write the .env.local the app needs, then run Vite
cargo-ai hosting app env <app-uuid> > ./territories/.env.local
cd ./territories && npm install && npm run dev

# 4. Build & upload (source = package root, not dist/). The backend runs `npm ci && vite build`.
cargo-ai hosting deployment create --app-uuid <app-uuid> --source ./territories
# → { "uuid": "<deployment-uuid>", "status": "...", ... }

# 5. Poll until the build is terminal
cargo-ai hosting deployment get <deployment-uuid>

# 6. Promote to make it live at https://territories.cargo.app
cargo-ai hosting deployment promote --uuid <deployment-uuid>

# 7. Confirm what's live
cargo-ai hosting deployment get-promoted --app-uuid <app-uuid>

List and inspect

cargo-ai hosting app list                       # all apps in the workspace
cargo-ai hosting app list --folder-uuid <uuid>  # only apps in one folder
cargo-ai hosting app get <app-uuid>             # one app's details + live URL

Local development env

app env prints the .env.local lines a local copy of the app needs — Cargo OAuth client, workspace UUID, app UUID, and API URL — so getCargoEnv() / useCargoApi() talk to the right workspace.

# Default API URL (https://api.getcargo.io)
cargo-ai hosting app env <app-uuid> > ./my-app/.env.local

# Point at a different API (e.g. a staging environment)
cargo-ai hosting app env <app-uuid> --api-url https://api.staging.getcargo.io > ./my-app/.env.local

Rename, move, remove

# Rename
cargo-ai hosting app update --uuid <app-uuid> --name "Renamed App"

# Move into a folder (folders are managed by cargo-workspace-management)
cargo-ai workspaceManagement folder list                          # find the folder UUID
cargo-ai hosting app update --uuid <app-uuid> --folder-uuid <folder-uuid>

# Move back to the workspace root (literal string "null")
cargo-ai hosting app update --uuid <app-uuid> --folder-uuid null

# Remove (also removes every deployment of this app)
cargo-ai hosting app remove <app-uuid>

Ship a new version of an existing app

The app slot and slug stay put; you just create and promote a fresh deployment.

cargo-ai hosting deployment create --app-uuid <app-uuid> --source ./my-app
# poll deployment get <new-deployment-uuid> until terminal
cargo-ai hosting deployment promote --uuid <new-deployment-uuid>

Roll back by promoting an earlier deployment — deployment list --app-uuid <uuid> shows the history; deployment promote --uuid <older-uuid> points the live URL back at it.

3.2 KiB Raw Permalink Blame History