CLI setup and authentication

Run the CLI from your terminal or agent with npx shiplet-cli. It opens your browser so you can approve a session without copying credentials.

Install and run

Use Node.js 22.12.0 or newer. The public npm package needs no source checkout or npm account.

npx shiplet-cli --help
npx shiplet-cli prepare ./dist --name "Review build" --subdomain review-build --visibility organization --dry-run --json

The unscoped npm package shiplet belongs to an unrelated project. Use npx shiplet-cli, not npx shiplet, for this product.

All commands below also work with npx shiplet-cli in place of shiplet. To use the shorter shiplet commands, install globally:

npm install -g shiplet-cli
shiplet --help

Replace ./dist with your artifact folder and choose an available subdomain. Add --dry-run to inspect the artifact before publishing; a dry run does not authenticate.

Approve a session

1. Run shiplet login, or any network command without an API key, to use browser authorization.
2. Sign in to Shiplet if asked. Check the account shown on the approval page.
3. Select Authorize CLI only if you started the command.
4. Select Return to CLI on the approval page to complete the local callback.
5. Return to your terminal or agent for the result. You can close the browser window.

One approval creates a session that later commands reuse for two hours by default. Set another length with --session-ttl or SHIPLET_CLI_SESSION_TTL, from 5 minutes to 8 hours; Shiplet enforces the 8 hour maximum. The session is bound to the exact Shiplet origin and the approved account, and is kept in the macOS Keychain, the Linux Secret Service keyring, or otherwise a user-only 0600 file under ~/.config/shiplet. It is never printed. No pasted credential is required.

Run shiplet whoami to see the account, origin, and expiry, and shiplet logout to revoke the session on Shiplet immediately and delete it locally. To approve every command separately instead, pass --no-session-cache or set SHIPLET_CLI_SESSION_CACHE=0.

Your existing access still applies. A saved session can also deploy, promote, and roll back while it lasts, and each of those commands still requires --approve. Keep the lifetime short and log out when you finish.

If authorization stops

For an expired request, canceled approval, or mismatched callback, run the command again and use the new browser window. Run the CLI and browser on the same computer so the browser can reach the local callback. For a remote or headless agent, use a narrowly scoped organization API key from a secret store for supported commands, or supported MCP.

Other authentication routes

• Human review: sign in in the browser.
• MCP clients: use Code Mode MCP with browser OAuth or supported agent registration.
• CI and unattended jobs: use narrowly scoped organization API keys from a secret store.