@otakit/cli

@otakit/cli

Upload and release CLI for OtaKit.

What it does

• reads project config from capacitor.config.*
• authenticates with login or env tokens
• zips the build output
• computes the bundle SHA-256 checksum
• creates an upload session
• uploads the zip directly to object storage
• finalizes the bundle
• optionally releases it to the unnamed channel or a named channel

The normal hosted flow is dashboard-first. Create the app in the dashboard, paste its appId into plugins.OtaKit.appId, then ship:

otakit login
npm run build
otakit upload --release

If you want to create the app from the CLI instead:

otakit register --slug com.example.app

There is no otakit init.

Config model

The CLI reads these files when present:

• capacitor.config.ts
• capacitor.config.js
• capacitor.config.mjs
• capacitor.config.cjs
• capacitor.config.json

Important values:

webDir: "out",
plugins: {
  OtaKit: {
    appId: "app_xxxxxxxx",
    // Optional:
    // channel: "staging",
    // serverUrl: "https://your-server.com/api/v1"
  }
}

Resolution order:

• CLI flags
• environment variables
• capacitor.config.*
• built-in defaults

Main rules:

• appId: --app-id -> OTAKIT_APP_ID -> plugins.OtaKit.appId
• serverUrl: --server -> OTAKIT_SERVER_URL -> plugins.OtaKit.serverUrl -> https://console.otakit.app
• outputDir: upload path arg -> OTAKIT_BUILD_DIR / OTAKIT_OUTPUT_DIR -> webDir
• release channel: --release -> unnamed channel, --release <channel> -> named channel

Auth precedence:

• OTAKIT_TOKEN
• stored token from otakit login

Organization rules:

• organization API keys stay bound to their organization
• app-scoped commands use the organization that owns the app
• app-less commands use the default chosen during login; automation can set OTAKIT_ORGANIZATION_ID
• otakit organization select changes the local default without changing the dashboard workspace

Version precedence:

• --version
• OTAKIT_VERSION
• auto-generated <base>+otk.<commit>.<run>

Release model

• otakit upload upload only
• otakit upload --release upload and release to the unnamed channel
• otakit upload --release staging upload and release to a named channel
• otakit release <bundleId> --channel staging promote an existing bundle later

Releases are append-only. The newest release for (appId, channel, runtimeVersion) is what devices see on manifest checks. A release made with --rollout <percent> reaches that share of devices on plugin 3.1+ first, while the rest stay on the previous release until it completes.

Common commands

• otakit login
• otakit logout
• otakit whoami
• otakit organization select
• otakit register --slug <slug>
• otakit upload [path] [--release [channel]]
• otakit upload --release --auto-revert [--auto-revert-rate <1-95>] [--auto-revert-min-sample <10-100000>] — server reverts the release if too many devices roll back within 24h (defaults: 20% of ≥50)
• otakit release [bundleId] [--channel <channel>] [--rollout <percent>] [--replace-rollout]
• otakit release [bundleId] --notes <text> or --notes-file <path> — plain-text release notes (up to 2,000 characters) that apps on plugin 3.3+ can show once; also on otakit upload --release
• otakit rollout [releaseId] [--channel <channel> | --base] [--percent <n> | --complete | --cancel] — show or change active rollouts
• otakit preview [bundleId] [--expires <1h|24h|7d|30d>] [--scheme <scheme>] — private link and QR code that open a bundle in the installed app (plugin 3.2+, previewLinks: true); --list, --revoke <previewId>
• otakit upload --preview — upload, then print a preview link and QR code
• otakit releases [--channel <channel> | --base]
• otakit list
• otakit diff <bundleId> [--against <bundleId> | --channel <channel> | --base] [--json] — files added, changed and removed, sizes, what devices download, and warnings about content that should not ship
• otakit delete <bundleId> --force
• otakit push send --title <title> --body <body> [--url <path>] [--topic <t>] [--channel <c>] [--user <id>] [--yes] — send a push notification (Push notifications add-on)
• otakit push campaigns / otakit push campaign <id> — delivery status
• otakit config validate
• otakit config resolve --json
• otakit generate-signing-key
• otakit mcp [--project-root <path>]

MCP server

Run the local stdio server from the Capacitor project it should access:

npx -y @otakit/cli@latest mcp

The project root and organization are fixed when the server starts. For a configured project, the CLI uses plugins.OtaKit.appId to select its owning organization and the server verifies current membership. An organization key is already fixed to its owning organization. For app-less projects, otakit login stores a named default; change it with otakit organization select and restart the MCP connection. Users do not need an organization ID for interactive setup.

Do not put an OtaKit token in tool arguments. The server reuses OTAKIT_TOKEN or the stored otakit login session and honors OTAKIT_SERVER_URL for self-hosted installations. App-less automation may set OTAKIT_ORGANIZATION_ID; the --organization-id flag remains an advanced per-process override.

The hosted remote server is https://console.otakit.app/mcp. It is a separate, deployment-enabled surface for account operations and cannot read or upload files from your local project. A deployment that has not enabled it returns a clear 503 response; local stdio MCP continues to work independently. See the MCP and Agent Skills guide for Claude Code, Codex, OAuth scopes, and remote setup.

CI

export OTAKIT_TOKEN=otakit_sk_...
export OTAKIT_APP_ID=app_xxxxxxxx
export OTAKIT_BUILD_DIR=out

otakit upload --release

Set OTAKIT_SERVER_URL only for custom or self-hosted servers.

Upload flow

• resolve the build output directory
• require index.html
• zip the output
• compute SHA-256 and size
• call bundles/initiate
• upload directly to object storage
• call bundles/finalize
• optionally call releases

The CLI does not own app creation or channel strategy. It packages the build, uploads it, and optionally promotes it.

Build locally

pnpm --filter @otakit/cli build
pnpm --filter @otakit/cli typecheck
pnpm --filter @otakit/cli dev