@star-factory/launch-cli

Official CLI and local stdio MCP server for launching permissionless Star tokens.

The agent never handles wallet secrets or mint keypairs. Users authorize with Star in the browser, and Star derives the launch wallet, reserves a Star vanity mint, submits the launch, and reports status.

Quickstart: launch a token in 60 seconds

# 1. Authorize this device (opens a Star login URL + user code)
npx -y @star-factory/launch-cli star launch login

# 2. Preview exactly what will be sent (no mutation)
npx -y @star-factory/launch-cli star launch create \
  --name "My Agent Token" \
  --ticker AGENT \
  --website https://example.com \
  --dry-run --json

# 3. Launch for real and wait until the token is live
npx -y @star-factory/launch-cli star launch create \
  --name "My Agent Token" \
  --ticker AGENT \
  --website https://example.com \
  --yes --wait-until live --timeout 30m --json

Install

npm install -g @star-factory/launch-cli
star --version
star --help

One-off package-manager execution:

npx -y @star-factory/launch-cli --help
pnpm dlx @star-factory/launch-cli --help
yarn dlx @star-factory/launch-cli --help

Use STAR_AGENT_CONFIG when an agent runs in a shared or temporary environment:

export STAR_AGENT_CONFIG="$(mktemp -d)/agent.json"

Use --api-url on login when testing a preview deployment. Keep the same Star URL for auth, validation, creation, and status checks.

Auth

Every mutation requires a scoped Star agent token.

star launch login --api-url https://star.fun
star launch whoami --json

login prints a Star URL and user code separately. Open the URL, sign in with Star's Privy-backed login, enter the code shown by the CLI, and let the CLI finish polling. The token is opaque, stored locally with private file permissions, and can be revoked server-side.

whoami confirms the saved session and launch wallet:

{
  "schemaVersion": "star.launch-agent/v1",
  "ok": true,
  "command": "launch.whoami",
  "data": {
    "userId": "...",
    "launchWallet": "..."
  }
}

Stop if data.launchWallet is missing. The user needs to finish wallet setup on Star.

Launch With Direct Fields

Direct fields are best for chat agents because the user can approve exactly what will be sent.

star launch validate \
  --name "My Agent Token" \
  --ticker AGENT \
  --website https://example.com \
  --json

star launch create \
  --name "My Agent Token" \
  --ticker AGENT \
  --website https://example.com \
  --dry-run \
  --json

star launch create \
  --name "My Agent Token" \
  --ticker AGENT \
  --website https://example.com \
  --yes \
  --wait-until live \
  --timeout 30m \
  --idempotency-key agent-run-001 \
  --json

Optional direct fields:

--x stardotfun
--description "Short public description"
--elevator-pitch "Why this token should exist"
--token-utility "How the token is used"

Launch From A File

Use a file when the user or agent already has a reviewed payload.

{
  "formData": {
    "projectDetails": {
      "name": "My Agent Token",
      "ticker": "AGENT"
    },
    "social": {
      "websiteUrl": "https://example.com"
    }
  }
}

Commands:

star launch validate --file launch.json --json
star launch create --file launch.json --dry-run --json
star launch create --file launch.json --yes --wait-until live --timeout 30m --json

create waits for live by default. Use --no-wait only when another process will watch status. Use --wait-until launch_requested only for low-level diagnostics.

Required Fields

| Field | Requirement | | ------------------------ | ----------------------------------------------------------------- | | name | Non-empty token or project name | | ticker | letters A-Z and digits 0-9; lowercase is accepted and normalized | | website / websiteUrl | Non-empty website; Star adds https:// when no scheme is present | | x / xUsername | X username is optional; leading @ is stripped |

Do not provide userId, wallet secrets, mint addresses, mint keypairs, quote mint settings, or fundraise configuration. Star derives the identity and launch wallet from the authenticated account.

JSON Output

Pass --json for one stable envelope per command:

{
  "schemaVersion": "star.launch-agent/v1",
  "ok": true,
  "command": "launch.create",
  "data": {
    "ok": true,
    "idempotencyKey": "agent-run-001",
    "created": {
      "projectId": "...",
      "projectSlug": "...",
      "launchId": "..."
    },
    "status": {
      "launchId": "...",
      "status": "live",
      "baseMint": "...Star"
    }
  }
}

Always keep data.created.launchId or data.status.launchId. It is the recovery handle for timeouts, failures, and support.

Status

star launch status <launchId> --watch --wait-until live --timeout 30m --json

Common statuses:

| Status | Meaning | | ------------------ | ------------------------------------------------------------- | | launch_requested | Star accepted the request and queued on-chain launch work | | live | Token launch is live | | failed | Launch stopped with a typed failure | | timeout | CLI wait timed out; keep the launch id and check status again |

Errors

| Code | Agent response | | -------------------------------------------------- | ---------------------------------------------------------------- | | AUTH_REQUIRED, TOKEN_REVOKED, SCOPE_REQUIRED | Run star launch login, then retry | | AUTH_URL_MISMATCH | Use one allowlisted Star URL through the whole flow | | AUTH_WALLET_MISSING | Ask the user to finish Star wallet setup | | CONFIRMATION_REQUIRED | Ask for approval, then retry with --yes | | VALIDATION_FAILED | Show field errors and collect corrected values | | CAPACITY_UNAVAILABLE, INVENTORY_EMPTY | Tell the user Star launch capacity is temporarily unavailable | | KEEPER_FAILED | Report the launch id and sanitized failure; do not retry blindly | | TIMEOUT | Keep the launch id and continue status checks |

MCP

star mcp serve

Tools:

• star_auth_begin
• star_auth_poll
• star_auth_status
• star_launch_requirements
• star_launch_validate
• star_launch_token
• star_launch_status

Agents should parse structuredContent, not scrape text. star_launch_token accepts flat launch fields like name, ticker, websiteUrl, and optional xUsername; it requires confirmed: true unless dryRun: true.

Local Checks

node --test packages/star-launch-agent/test/*.test.mjs
npm --prefix packages/star-launch-agent run pack:check

License

MIT