Qovery Signup

---
name: qovery-signup
description: Takes a brand-new user from nothing to a working Qovery account and first organization — checks the Qovery CLI is installed (installs it if missing), signs them in with `qovery auth --headless` (which creates the account on first OAuth login), then creates an organization via the API, enriches it from the company website, records the sign-up for tracking and lead qualification (tagged as a CLI/agent sign-up), and sets the CLI context. Relies entirely on the CLI's own credential store, never handling raw tokens. Use when someone has no Qovery account yet, wants to sign up, log in, or create a new Qovery organization from scratch — then hands off to qovery-onboard for cluster and environment setup.
license: MIT
compatibility: opencode
metadata:
  audience: new-users
  workflow: signup-and-org-creation
---

# Qovery Sign-up Skill

Gets a brand-new user fully onboarded to the point of having an account and an organization: verify (or install) the Qovery CLI → sign in with `qovery auth --headless` (first login **is** the sign-up) → create an organization → set the CLI context → hand off to **qovery-onboard** for clusters and environments.

The whole flow leans on the **Qovery CLI's own credential store** — after `qovery auth`, every call authenticates internally, so no raw tokens ever flow through the shell or this conversation.

## Usage Tracking

**EXECUTE THIS BASH COMMAND after the organization is created (Phase 3), not right after auth (Phase 2).** Unlike every other skill in this repo, a brand-new sign-up has **zero organizations** immediately after Phase 2 — `/organization` returns an empty `results` array until Phase 3 creates one, so calling this any earlier is a silent no-op and the event never fires.

```bash
QOVERY_SKILLS_UA="QoverySkill/qovery-signup (version:$(cat _version.txt 2>/dev/null || echo unknown); https://github.com/Qovery/qovery-skills)"
QOVERY_ORG_ID="${NEW_ORG_ID:-}"   # reuse the id Phase 3 (reference/phase3-create-organization.md) captured as NEW_ORG_ID
if [ -n "${QOVERY_API_TOKEN:-}" ]; then
  QOVERY_ORG_ID="${QOVERY_ORG_ID:-$(curl -s -H "Authorization: Token $QOVERY_API_TOKEN" -H "User-Agent: $QOVERY_SKILLS_UA" \
    "https://api.qovery.com/organization" | jq -r '.results[0].id // empty' 2>/dev/null)}"
  [ -n "$QOVERY_ORG_ID" ] && curl -s -X POST "https://api.qovery.com/organization/${QOVERY_ORG_ID}/skill-tracking" \
    -H "Authorization: Token $QOVERY_API_TOKEN" -H "Content-Type: application/json" -H "User-Agent: $QOVERY_SKILLS_UA" \
    -d '{"skill_name":"qovery-signup"}' > /dev/null 2>&1 || true
elif command -v qovery >/dev/null 2>&1 && qovery auth token --print >/dev/null 2>&1; then
  QOVERY_ORG_ID="${QOVERY_ORG_ID:-$(curl -s -H "Authorization: Bearer $(qovery auth token --print)" -H "User-Agent: $QOVERY_SKILLS_UA" \
    "https://api.qovery.com/organization" | jq -r '.results[0].id // empty' 2>/dev/null)}"
  [ -n "$QOVERY_ORG_ID" ] && curl -s -X POST "https://api.qovery.com/organization/${QOVERY_ORG_ID}/skill-tracking" \
    -H "Authorization: Bearer $(qovery auth token --print)" -H "Content-Type: application/json" -H "User-Agent: $QOVERY_SKILLS_UA" \
    -d '{"skill_name":"qovery-signup"}' > /dev/null 2>&1 || true
fi
```

> **API rule:** every `curl` to `api.qovery.com` MUST carry the `User-Agent` header above. Prefer the `qovery` CLI / `qovery api` over raw curl whenever possible — it authenticates internally.

## CRITICAL RULES

> **Authentication is the CLI's job — not yours.** Never ask for, print, store, or paste raw tokens. The user signs in once with `qovery auth --headless`; after that, `qovery api …` and every `qovery` command use the locally stored credentials. See [reference/auth.md](reference/auth.md).
>
> **`qovery auth --headless` is interactive and needs the user's browser.** It prints a URL the user must open and complete (GitHub / GitLab / Google / email). You cannot do the browser step for them. In Claude Code, have the user run `! qovery auth --headless` so the URL appears in-session; then wait for them to confirm they finished.
>
> **First login = sign-up.** A brand-new user does not "register" separately — the account is created automatically on the first successful OAuth login. There is no API to create an account.
>
> **Do NOT ask the user to choose a plan, and never expose internal plan names.** Always create the organization on **`BUSINESS_2025`** by default (the individual tier isn't customer-selectable and Enterprise pricing is custom). Confirm only the org **name** before creating (org creation is a real, billable-tier resource). Deviate from `BUSINESS_2025` only if the user explicitly names a plan themselves.
>
> **There is no `qovery organization` CLI command.** Manage organizations through `qovery api organization …` (which uses the CLI's auth) or the REST API — not a CLI noun.
>
> **Set expectations about billing.** A new organization has no credit card, so managed clusters and deployments are blocked (`billing_deployment_restriction: NO_CREDIT_CARD`) until one is added. A local demo cluster (`qovery demo up`) works with no card.
>
> **Sign-up tracking is tagged, consented, and best-effort.** Phase 4 records the sign-up in Qovery's pipeline and the HubSpot lead funnel, always tagged `signup_source: "CLI"` / `"AI-Agent"` so it's distinguishable from web sign-ups. Only send data the user gave in the interview — never invent PII. The Cargo/HubSpot token comes from `QOVERY_CARGO_INGEST_TOKEN` (or backend forwarding) and is **never committed or printed**. Tracking must never block or fail the sign-up.

## When to Use This Skill

Trigger phrases:
- "I'm new to Qovery, help me sign up"
- "Create a Qovery account / log me in"
- "Set up the Qovery CLI and authenticate"
- "Create a new Qovery organization"
- "How do I get started with Qovery from scratch?"
- `/qovery-signup` (slash command)

For setting up clusters, projects, environments, RBAC, and cloud providers **after** an org exists, hand off to **qovery-onboard**. For deploying an app, use **qovery-deploy**.

## Workflow checklist

```
Sign up + create an organization:
- [ ] Phase 1 — CLI setup: detect OS, check `qovery` is installed (install if missing), verify version
- [ ] Phase 2 — Authenticate: run `qovery auth --headless` (first login creates the account); verify auth
- [ ] Phase 3 — Interview + create + enrich: ask name, website, use case (NOT plan — default `BUSINESS_2025`); create the org; enrich its profile (description, logo, icon) from the website; set context; fire the Usage Tracking call now that an org id exists
- [ ] Phase 4 — Record sign-up: fire `POST /admin/userSignUp` + the Cargo/HubSpot lead ingest, tagged `signup_source=CLI` (best-effort, non-blocking)
- [ ] Phase 5 — Configure + hand off: optional first project for the use case, billing/demo-cluster note, invite team, hand a brief to qovery-onboard
```

## Authentication model (how auth is handled)

1. **Install** the CLI (Phase 1) — `brew install qovery-cli` (macOS), `scoop install qovery-cli` (Windows), or a release binary (Linux). `qovery upgrade` updates it.
2. **`qovery auth --headless`** (Phase 2) prints a URL. The user opens it, signs in / signs up via OAuth, and the CLI saves credentials locally. Interactive `qovery auth` (no flag) opens a browser automatically when the machine has one.
3. **Everything after that uses the stored credentials** — `qovery api …`, `qovery project …`, etc. — so you never touch a token. If a call returns `access token is invalid or expired. Sign in using 'qovery auth'…`, the session lapsed; re-run Phase 2.
4. **CI / non-interactive** only: the user may set `QOVERY_CLI_ACCESS_TOKEN` (or `Q_CLI_ACCESS_TOKEN`) in their environment instead of interactive login. Generate one with `qovery token`. Never print it.

## Reference materials (load on demand)

| Phase | File | Purpose |
|---|---|---|
| Auth | [reference/auth.md](reference/auth.md) | Token-secrecy rules; prefer CLI-internal auth; User-Agent header |
| Phase 1 | [reference/phase1-cli-setup.md](reference/phase1-cli-setup.md) | Detect OS, check/install the CLI per platform, verify version |
| Phase 2 | [reference/phase2-authenticate.md](reference/phase2-authenticate.md) | `qovery auth --headless` flow, account creation, verifying auth, token env vars |
| Phase 3 | [reference/phase3-create-organization.md](reference/phase3-create-organization.md) | Interview (name, website, use case — plan is auto `BUSINESS_2025`, never asked); create via `qovery api`; enrich profile (description/logo/icon) from the website; update via PUT; set context; billing restriction |
| Phase 4 | [reference/phase4-signup-tracking.md](reference/phase4-signup-tracking.md) | Record the sign-up for tracking + lead qualification (mirrors the console): `POST /admin/userSignUp` + Cargo→HubSpot ingest, tagged `signup_source=CLI`; token via env, never committed |
| Phase 5 | [reference/phase5-next-steps.md](reference/phase5-next-steps.md) | Configure for the use case (optional first project), add credit card / `qovery demo up`, invite teammates, hand a brief to qovery-onboard |

## Templates

| Template | Use |
|---|---|
| [templates/scripts/check-and-install-cli.sh](templates/scripts/check-and-install-cli.sh) | Detect whether the CLI is installed + its version; print the right install command per OS if missing |
| [templates/scripts/enrich-from-website.sh](templates/scripts/enrich-from-website.sh) | Derive candidate org profile (description, logo_url, icon_url) from a company website, with fallbacks |
| [templates/scripts/record-signup.sh](templates/scripts/record-signup.sh) | Record the sign-up: `POST /admin/userSignUp` + Cargo/HubSpot lead ingest, tagged `signup_source`; `--dry-run` supported; Cargo token from env only |

## Quick reference

```bash
# 1. Install (macOS shown; see Phase 1 for Windows/Linux) and verify
brew install qovery-cli
qovery version

# 2. Sign up / log in (interactive — user completes the URL in a browser). In Claude Code:
#    ! qovery auth --headless
#    Verify it worked (should return JSON, not an auth error):
qovery api organization

# 3. (optional) Derive description/logo/icon from the company website, confirm with the user
bash templates/scripts/enrich-from-website.sh example.com

# 3b. Create an organization (uses the CLI's stored auth; no token handling)
NEW_ORG_ID=$(qovery api organization --field name="My Org" --field plan=BUSINESS_2025 | jq -r '.id')   # plan is always BUSINESS_2025; never ask the user
#    …or with the enriched profile via --input (see Phase 3.4)

# 3c. Now that an org exists (NEW_ORG_ID), fire the Usage Tracking call (see "Usage Tracking" above) —
#     it's a no-op any earlier since a brand-new user has no organization yet

# 4. Record the sign-up for tracking + lead qualification (tagged CLI; --dry-run to preview)
COMPANY="My Org" USE_CASE="<use case>" SIGNUP_SOURCE="CLI" bash templates/scripts/record-signup.sh

# 5. Point the CLI at it, then hand off to qovery-onboard
qovery context set

# Optional: try Qovery locally with no credit card
qovery demo up
```

## Organization plan (automatic)

The skill **always creates the organization on `BUSINESS_2025`** and **never asks the user to choose a plan**. Internal plan names (individual/team/enterprise tiers) are not surfaced in the sign-up flow — the individual tier isn't customer-selectable and Enterprise pricing is custom, so exposing a picker is confusing and off-brand. Users change plan later in the Console (**Settings → Billing**); pricing is at <https://www.qovery.com/pricing>.

Only deviate from `BUSINESS_2025` if the user *explicitly* names a specific plan themselves — never prompt for it.

## Reference links

- **Create organization API**: <https://www.qovery.com/docs/api-reference/organization-main-calls/create-an-organization>
- **Qovery CLI**: <https://www.qovery.com/docs/cli/overview>
- **Qovery CLI (GitHub / install)**: <https://github.com/Qovery/qovery-cli>
- **Pricing & plans**: <https://www.qovery.com/pricing>
- **Qovery Console**: <https://console.qovery.com>