CLI reference

The command surface of @star-factory/launch-cli 0.4.0. Install with npm install --global @star-factory/launch-cli@0.4.0, or run one-off with npx -y @star-factory/launch-cli@0.4.0 <command>. Every command accepts --json and returns one stable envelope per command (schemaVersion: star.launch-agent/v2) carrying ok, command, the environment that answered, data, and error.

Environment

Production is the default and needs no selector. --env staging targets staging and --api-url <origin> targets a custom origin; both are global, may appear before or after the command, and apply to that one invocation only. Nothing is remembered between commands, so a staging session carries --env staging on every command (or exports STAR_ENV=staging). Tokens are stored per origin, so each environment is authorized separately.

Launch commands

Command	Purpose
`star launch requirements`	Unauthenticated read of the deployment’s launch contract: required fields, the four founder decisions with Star’s prompts, and tier economics. Start here
`star launch login`	Authenticate with a scoped Star agent token for the selected environment
`star launch whoami`	Show the current session and launch wallet
`star launch x-verify`	Prove an X handle. Unverified handles are dropped at launch
`star launch validate`	Validate a launch configuration without a mutation
`star launch create`	Create the launch. Supports `--file launch.json`, `--dry-run`, `--yes`, `--wait-until live`, `--timeout`, `--idempotency-key`
`star launch status <launchId>`	Launch status. Supports `--watch`, `--wait-until`, `--timeout`
`star launch logout`	End the session for the selected environment (`--all` for every environment)

Founder decisions

star launch create and star launch validate carry four founder decisions. None has a default: on a terminal create asks for whatever you left out; with --json, off a terminal, or from a file that omits one, it returns DECISION_REQUIRED naming the unanswered questions.

Flag	Decision
`--tier <id>`	Raise tier: one of the ids `star launch requirements` lists. Locked at launch
`--equity-link <percent>`	Equity link: a whole percent within the published bounds. Locked at launch
`--compensation-bands` / `--no-compensation-bands`	Create the complete, all-or-none compensation-band plan, or none
`--launch-rewards` / `--no-launch-rewards`	Reserve the Launch Rewards allocation for founder-created campaigns, or none

The tier ids, equity-link bounds, and the token amounts each choice reserves are published by star launch requirements and returned in the --dry-run preview. The CLI ships no economics of its own. Recommended sequence: launch requirements → launch login → launch create … --dry-run --json → review → launch create … --yes --json.

Rewards commands

Command	Purpose
`star rewards login`	Authenticate with rewards-management scope
`star rewards requirements`	Machine-readable campaign field requirements. Start here
`star rewards validate`	Validate a campaign configuration without a mutation
`star rewards create`	Create the campaign
`star rewards integration-bundle`	Download the partner integration bundle
`star rewards action-setup`	Configure an action-reward pool
`star rewards action-status`	Pool funding and activation state
`star rewards action-activate`	Activate a funded pool
`star rewards publish`	Publish the campaign
`star rewards participant-score`	Read one participant’s score
`star rewards leaderboard`	Read the campaign leaderboard

MCP server

star mcp serve

Starts the local stdio MCP server. The server is launch-focused; rewards management is CLI-only today. Tools:

Tool	Purpose
`star_auth_begin`	Start device auth. Returns `authorizeUrl` and `userCode`
`star_auth_poll`	Poll once. Returns `AUTH_PENDING` until the user approves
`star_auth_status`	Current session: `environment`, `authenticated`, `launchWallet`, scopes
`star_launch_requirements`	The deployment’s requirements: decisions with Star’s own prompts, tier economics, policies. Unauthenticated
`star_launch_validate`	Validate a configuration without a mutation. Reports `missingDecisions`
`star_launch_token`	Create the launch. Carries the four decisions; requires `confirmed: true` unless `dryRun`
`star_launch_status`	Status by `launchId`: `status`, `baseMint`, failure code

Every tool that talks to Star accepts a per-call environment (production or staging) or apiUrl; without one it uses the environment star mcp serve was started with. Every result names the environment it answered for. A call that omits a founder decision is answered with DECISION_REQUIRED and the unanswered questions in error.details.questions, never a default. Agents should parse structuredContent, not scrape text. Invalid arguments return INVALID_TOOL_INPUT before any network call.

Use it from Codex or Claude

mcp add registers the tools. It does not install the skill. Until the star-launch-agent plugin is listed, install the CLI, copy the skills, then register MCP. The same steps, with host-specific paths, are in the Quickstart.

# Claude Code — CLI + skill + MCP (user scope = every project)
npm install --global @star-factory/launch-cli@0.4.0
mkdir -p ~/.claude/skills
cp -R "$(npm root -g)/@star-factory/launch-cli/skills/." ~/.claude/skills/
claude mcp add --scope user star -- npx -y @star-factory/launch-cli@0.4.0 mcp serve

# Codex CLI — same three steps; skills live in ~/.agents/skills
npm install --global @star-factory/launch-cli@0.4.0
mkdir -p ~/.agents/skills
cp -R "$(npm root -g)/@star-factory/launch-cli/skills/." ~/.agents/skills/
codex mcp add star -- npx -y @star-factory/launch-cli@0.4.0 mcp serve

Errors

Code	Action
`AUTH_REQUIRED`, `TOKEN_REVOKED`, `SCOPE_REQUIRED`	Run `star launch login` or `star rewards login`, then retry
`DECISION_REQUIRED`	Ask the founder the listed questions, then retry with every decision supplied
`CONFIRMATION_REQUIRED`	Ask for approval, then retry with `--yes` (CLI) or `confirmed: true` (MCP)
`INVALID_TOOL_INPUT`	Fix the arguments. No network call was made

Security model: agents never hold wallet secrets or keypairs, and nothing launches until you approve the exact payload. See the Quickstart.

Start

Your token

Your raise

After the raise

Reference

About

Environment

Launch commands

Founder decisions

Rewards commands

MCP server

Use it from Codex or Claude

Errors

​Environment

​Launch commands

​Founder decisions

​Rewards commands

​MCP server

​Use it from Codex or Claude

​Errors

Environment

Launch commands

Founder decisions

Rewards commands

MCP server

Use it from Codex or Claude

Errors