Qovery Signup

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.

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.

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)

Templates

Quick reference

# 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