onboarding

CircleCI Onboarding

Guide the user through setting up CircleCI from scratch. Work through the stages below in order. At each stage, use AskUserQuestion to collect structured input rather than asking in prose — this keeps the flow crisp and unambiguous. Run CLI commands to verify state before asking questions you can answer yourself. Skip stages that are already complete.

Stage 0: Check prerequisites

First, verify the CLI version:

circleci version

Extract the version number from the output (e.g. circleci 0.1.2+... → 0.1.2). If the major version is 0 (i.e. below 1.0.0), stop and tell the user:

"This onboarding flow requires CircleCI CLI version 1.0.0 or later. Your installed version is <version>. Please upgrade with:

brew tap circleci-public/homebrew-circleci
brew remove circleci
brew install --cask circleci@next
```"

Do not proceed past this stage if the version check fails.

Then run circleci auth me before asking anything. If it returns a user, skip Stage 1 and note the username.

Stage 1: Account

If not authenticated, ask:

AskUserQuestion(
  "Are you new to CircleCI or do you already have an account?",
  header: "Account",
  options: [
    { label: "New — create an account", description: "Open signup in browser via circleci auth signup" },
    { label: "Existing — log in",        description: "Open login in browser via circleci auth login" }
  ]
)

Then run the appropriate command and verify with circleci auth me.

Stage 2: Org

Ask:

AskUserQuestion(
  "Which CircleCI org do you want to use?",
  header: "Organization",
  options: [
    { label: "Use an existing org",  description: "I'll provide the org slug" },
    { label: "Create a new org",     description: "I'll walk you to app.circleci.com/organization-setup" }
  ]
)

• Existing: Ask for the slug via a follow-up text input (e.g. gh/myorg or circleci/<uuid>). Found at Organization Settings → Organization slug.
• New: Direct to https://app.circleci.com/organization-setup, wait for confirmation, then ask for the resulting slug.