메인 콘텐츠로 건너뛰기

CLI quickstart

Install the SprintX CLI, connect it with sx auth, select a project, send the first event and artifact, then verify the connection with sx status and sx brief.

This guide is the detailed CLI reference for the minimum SprintX connection flow.

In one line: install the CLI, run sx auth, choose a project with sx project use, send one sx event, add one sx artifact, then confirm the result with sx status and sx brief.

Install the CLI

The CLI package name is @sprint-x/cli and it installs the sx binary.

npm install -g @sprint-x/cli
sx --help

If your runtime already manages the install step for you, move straight to sx auth.

1. Connect the CLI with sx auth

sx auth links the local CLI installation to the signed-in SprintX account.

sx auth

What happens:

  1. The CLI requests a SprintX approval URL.
  2. In interactive mode it opens the browser for you.
  3. After approval, the CLI stores the local session for later commands.

Important boundary:

  • sx auth is for the SprintX account session.
  • Provider keys such as Anthropic or OpenAI stay separate in /settings.

2. Select the project with sx project use

If you already know the project UUID from the handoff entry card, use it directly:

sx project use 11111111-1111-4111-8111-111111111111

Successful output includes:

  • project_id
  • receipt_id

Run sx project list only when you need to recover the UUID or inspect shared projects:

sx project list
# * 11111111-1111-4111-8111-111111111111	My Current Project
#   22222222-2222-4222-8222-222222222222	Shared Project

Choose the project once, then reuse it for later event, artifact, status, and brief commands.

Use this when:

  • you need to look up the project UUID from the CLI before selection
  • one runtime mostly works in one project
  • you want a stored default instead of passing --project every time

3. Send the first execution signal with sx event

sx event sends a project-scoped runtime event to SprintX.

sx event \
  --type runtime.started \
  --summary "Initial OpenClaw handoff started" \
  --metadata '{"source":"openclaw","taskId":"task_123"}'

Common flags:

  • --type required event type
  • --summary short human-readable summary
  • --metadata JSON payload
  • --project temporary project override
  • --runtime-instance-id runtime identifier for audit

Notes:

  • The CLI generates an idempotency key automatically.
  • If the stored project context is missing or stale, the CLI retries after repairing the project selection.

4. Add the first artifact receipt with sx artifact add

sx artifact add records an artifact reference in SprintX.

sx artifact add \
  --title "build-log" \
  --reference-uri "file:///tmp/build.log" \
  --content-type "text/plain" \
  --summary "First build output" \
  --metadata '{"kind":"log"}'

Common flags:

  • --title required artifact title
  • --reference-uri required file, https, or other reference URI
  • --content-type required content type
  • --summary short explanation
  • --metadata JSON payload
  • --project temporary project override

upload is still available as an alias:

sx artifact upload --title "build-log" --reference-uri "file:///tmp/build.log" --content-type "text/plain"

5. Verify what SprintX sees with sx status and sx brief

Once event and artifact are accepted, run the simple check commands right away.

sx status
sx brief

What a healthy result looks like:

  • sx status prints the project name, task totals, active sprint, active runs, and member count
  • sx brief prints the project name, open task count, active run count, and recent tasks
  • both commands work without re-passing the project id if sx project use already succeeded

This is the fastest way to confirm that SprintX is reading the same project your runtime thinks it is using.

Headless and CI usage

Use headless mode when the runtime should not try to open a browser window.

sx --headless auth

In headless mode:

  • the approval URL is printed to stdout
  • colors and spinners are disabled
  • you can copy the URL into a browser that already has the right SprintX session

The CLI also auto-detects headless environments when one of these is true:

  • stdout is not a TTY
  • CI is truthy
  • GITHUB_ACTIONS is truthy
  • OPENCLAW_SESSION is truthy

For fully non-interactive environments, provide an access token directly and skip browser auth:

export SX_ACCESS_TOKEN="<access-token>"
export SX_PROJECT_ID="proj_123"

sx event --type runtime.started --summary "CI handoff started"
sx artifact add --title "ci-log" --reference-uri "https://example.com/logs/1" --content-type "text/plain"

Environment variables

The CLI currently documents these environment variables:

VariableWhat it does
SX_API_URLOverrides the SprintX API base URL. Default: https://www.sprintx.co.kr
SX_ACCESS_TOKENDirect access token override. When present, sx auth skips browser auth
SX_PROJECT_IDDefault project for sx event and sx artifact add
SX_LANGLanguage override. Set ko to force Korean CLI copy
CIHelps auto-detect headless mode
GITHUB_ACTIONSHelps auto-detect headless mode
OPENCLAW_SESSIONHelps auto-detect headless mode

Minimum connection checklist

  • CLI installed and sx command available
  • sx auth completed
  • sx project use <projectId> completed
  • first sx event accepted
  • first sx artifact add accepted
  • sx status and sx brief return the project you expect

Next docs