> ## Documentation Index
> Fetch the complete documentation index at: https://docs.star.fun/llms.txt
> Use this file to discover all available pages before exploring further.
# CLI reference
The command surface of [`@star-factory/launch-cli`](https://www.npmjs.com/package/@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 `. 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 ` 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 ` | 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 ` | Raise tier: one of the ids `star launch requirements` lists. Locked at launch |
| `--equity-link ` | 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
```bash theme={null}
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](/quickstart#use-it-from-codex-or-claude).
```bash theme={null}
# 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](/quickstart).