firsty

Worldwide eSIM and mobile data from your terminal: the CLI for the Firsty Partners API.

npx firsty init          # claims a free sandbox credential, no account needed
npx firsty esim order    # provision an eSIM, get the activation code
npx firsty esim usage    # check consumption

Currently sandbox only: commands run against Firsty's staging environment and return mock data. Ready to go live? Talk to sales: https://developers.firsty.app/contact-sales

Setting up with a coding agent

Paste this into Claude Code, Cursor, Codex or any coding agent:

Use curl to read developers.firsty.app/agents.md and perform the setup to install the Firsty CLI

The guide at developers.firsty.app/agents.md walks the agent through install, credential claim and a first eSIM.

Commands

| Command | What it does | | ------- | ------------ | | firsty init | Set up: claim a sandbox credential and verify it | | firsty auth status / auth token | Inspect credentials / print a bearer token | | firsty catalog packages\|regions\|coverage\|devices\|variants | Browse the catalog | | firsty esim order\|list\|get\|usage | Provision and inspect eSIMs | | firsty esim suspend\|reactivate\|terminate | Lifecycle management | | firsty package order\|list | Put data/SMS/voice packages on an eSIM |

Every command takes --json for machine-readable output with a stable envelope ({ok, mode, data|error}) and documented exit codes. See agents.md for the full contract.

Development

Lives in the firsty-cli/ folder of the Firsty developer portal repo; a self-contained npm package (Node >= 20, TypeScript, commander, tsup, vitest).

npm install
npm run typecheck && npm test    # unit + command tests (msw-mocked API)
npm run build                    # bundles to dist/index.js
node dist/index.js --help

test/contract/ validates the CLI's assumptions against the committed OpenAPI spec (content/api-reference/openapi.json). The cli-ci workflow also runs on spec changes, so the spec sync bot's PRs fail if the API drifts from what the CLI encodes.

npm run test:e2e runs the staging smoke test (needs FIRSTY_E2E_CLIENT_ID/FIRSTY_E2E_CLIENT_SECRET).

Releases: bump the version, tag cli-v<version>, push the tag. The cli-release workflow publishes to npm via trusted publishing.