llms.txt
Compare with other sites' llms.txt files →# OtaKit Docs
Canonical documentation: https://otakit.app/docs
Generated from the public docs pages in `packages/site/app/docs`.
## Pages
- Overview: /docs
- Setup: /docs/setup
- CLI Reference: /docs/cli
- Plugin API: /docs/plugin
- REST API: /docs/api
- Next.js Guide: /docs/guide
- React Guide: /docs/react
- Channels: /docs/channels
- Rollouts: /docs/rollouts
- Previews: /docs/previews
- Release Notes: /docs/release-notes
- Update Strategies: /docs/update-strategies
- Events & Listeners: /docs/events
- Push Notifications: /docs/push
- CI Automation: /docs/ci
- MCP & Agent Skills: /docs/agents
- Security: /docs/security
- Self-hosting: /docs/self-host
- Changelog: /changelog
## Overview
Route: /docs
How OtaKit works and where to start.
OtaKit ships over-the-air updates for Capacitor apps. You build your web app, upload its bundle, and the plugin delivers that bundle to devices without store submissions or reviews.
Start with the quick setup
### How it works
1. Create an app in the OtaKit dashboard and copy its `appId` into your `capacitor.config.ts` file.
2. Call `notifyAppReady()` when your app finishes loading, so newly activated updates can be confirmed healthy.
3. Build your web app and run `otakit upload --release` to upload and publish a new bundle.
4. On device, the plugin checks for updates, verifies the downloaded bundle, and by default activates it on the next cold launch.
### Features
- **One-command shipping**: Build your web app, then release with otakit upload --release.
- **Channels & runtime lanes**: Channels for rollout tracks, runtimeVersion for native compatibility lanes — switchable at runtime with setChannel().
- **Delta updates**: Opt-in per-file updates: devices download only the files that changed between releases.
- **Automatic update delivery**: The normal flow checks and stages automatically, then activates according to the configured launch, resume, and runtime policies.
- **Force-immediate releases**: Emergency releases apply and reload on the device's next check, whatever its configured policies.
- **Update lifecycle events**: updateAvailable, updateStaged, updateApplied, downloadFailed, rollback — build your own update UX.
- **Manual update control**: Turn automatic policies off when your app wants to show its own update prompt or control install timing.
- **Safe activation & rollback**: A newly activated bundle must call notifyAppReady() or OtaKit rolls back automatically.
- **Signed & verified**: ES256-signed manifests and SHA-256 checks on every download, plus optional end-to-end encryption.
- **Native compatibility guardrail**: The CLI warns at upload time when a bundle depends on native code the installed app doesn't have.
- **MCP & Agent Skills**: Ask your coding agent to ship an update. It checks compatibility, uploads, and stops for your approval — the same release process, same audit trail.
- **Self-hosting**: Run OtaKit on your own infrastructure when you need full control over delivery and trust.
### Getting started
- **Quick setup**: Connect the default hosted OtaKit flow to your Capacitor app.
- **Next.js Guide**: Go from Next.js + Capacitor to your first OTA update.
- **Channels & Runtimes**: Rollout tracks vs runtime compatibility lanes, and when to use each.
- **Update Strategies**: How launchPolicy, resumePolicy, and runtimePolicy combine to control when updates apply.
- **MCP & Agent Skills**: One command connects Claude Code, Codex, or VS Code to your project.
- **CI Automation**: Build and ship bundles from GitHub Actions.
- **CLI Reference**: Commands, options, and release workflows.
- **Plugin API**: Default automatic flow, manual flow, and configuration.
Need help with setup, billing, or rollout issues? Email support@otakit.app .
## Setup
Route: /docs/setup
Set up the default hosted OtaKit flow in a Capacitor project.
This is the most simple, default hosted setup path.
### 1. Connect your app in the dashboard
Sign in to the OtaKit dashboard and choose “Connect your app”. Give it a label that is unique in your workspace, such as `my-app`; it does not need to match your native app ID.
OtaKit generates a separate app ID. Copy that generated value from the dashboard into `plugins.OtaKit.appId`, not the label you entered. The floating setup panel guides you through connecting your project.
### 2. Install the Capacitor plugin
```txt
npm install @otakit/capacitor-updater
npx cap sync
```
### 3. Configure the plugin
Add the OtaKit plugin to `capacitor.config.ts` and paste in the `appId` from the dashboard.
```txt
// capacitor.config.ts
import type { CapacitorConfig } from "@capacitor/cli";
const config: CapacitorConfig = {
appId: "com.example.myapp",
appName: "My App",
webDir: "out",
plugins: {
OtaKit: {
appId: "YOUR_OTAKIT_APP_ID",
}
}
};
export default config;
```
Build and install the native app with the OtaKit plugin configured before testing OTA. A local test build is enough to get started. To reach existing users, publish an App Store or Google Play build containing the plugin; those users can receive OtaKit updates after installing that build.
Optional: if you want something other than the hosted defaults, you can also set `launchPolicy`, `resumePolicy`, `runtimePolicy`, and `checkInterval`. See the Plugin API page for the full configuration surface.
### 4. Add notifyAppReady()
Call `notifyAppReady()` once your app has loaded. If the new bundle is activated and your app never confirms that it started successfully, OtaKit rolls back automatically.
```txt
import { OtaKit } from "@otakit/capacitor-updater";
await OtaKit.notifyAppReady();
```
For React-style apps, wrap it in a client-side effect:
```txt
"use client";
import { useEffect } from "react";
import { Capacitor } from "@capacitor/core";
import { OtaKit } from "@otakit/capacitor-updater";
export function AppReadyProvider() {
useEffect(() => {
if (Capacitor.isNativePlatform()) {
OtaKit.notifyAppReady();
}
}, []);
return null;
}
```
### 5. Install the CLI and sign in
```txt
npm install -g @otakit/cli
otakit login
```
### 6. Build and release
```txt
npm run build
otakit upload --release
```
That publishes the bundle to the base channel. By default, OtaKit downloads it in the background and activates it on the next cold app launch.
### Next
- Continue with the Next.js guide or React guide
- Read Channels & Runtimes for more advanced release flows.
- Use the Plugin API and CLI reference for exact configuration and command details.
## CLI Reference
Route: /docs/cli
Upload bundles, release them, inspect history, and manage apps with the OtaKit CLI.
Use the CLI to upload bundles, release them, inspect bundle and release history, and manage apps.
### Project config
Project commands read from `capacitor.config.*`.
```txt
// capacitor.config.ts
import type { CapacitorConfig } from "@capacitor/cli";
const config: CapacitorConfig = {
appId: "com.example.myapp",
appName: "My App",
webDir: "out",
plugins: {
OtaKit: {
appId: "app_xxxxxxxx",
// Optional named channel:
// channel: "staging"
// Optional compatibility lane:
// runtimeVersion: "2026.04"
}
}
};
export default config;
```
### Authentication
For local development, sign in once and the CLI stores a token locally. For CI or non-interactive environments, use an organization secret key instead.
If your account has multiple organizations, login asks you to choose a default by name for commands that are not tied to an app. Change it with `otakit organization select` . Configured apps still use their owning organization, and organization keys are already bound to one.
```txt
# Local development
otakit login
# CI / non-interactive
export OTAKIT_TOKEN=otakit_sk_...
export OTAKIT_APP_ID=app_xxxxxxxx
```
### Release flow
- Upload only: `otakit upload`
- Upload and release to the base channel: `otakit upload --release`
- Upload and release to a named channel: `otakit upload --release beta`
- Promote an existing bundle later: `otakit release <bundleId> --channel production`
### Resolution order
The CLI resolves values in a deterministic order.
- App ID: `--app-id` -> `OTAKIT_APP_ID` -> `capacitor.config.*`
- Server URL: `--server` -> `OTAKIT_SERVER_URL` -> `plugins.OtaKit.serverUrl` -> hosted default
- Auth token: `OTAKIT_TOKEN` -> stored login token
- App-less organization: `OTAKIT_ORGANIZATION_ID` -> stored login default
- Upload path: CLI path argument -> `OTAKIT_BUILD_DIR` -> `capacitor.config.* webDir`
- Release channel: `--release` -> base channel, `--release <channel>` -> named channel
- Runtime version: `plugins.OtaKit.runtimeVersion` -> bundle metadata during upload
- Upload version: `--version` -> `OTAKIT_VERSION` -> auto-generated version
### Command reference
### otakit upload [path]
Upload a bundle. Optionally release it immediately. Before uploading, the CLI warns about content that should not ship (.env files, .git, node_modules, native installers) and notes source maps and hidden files. After uploading, it prints what changed against the bundle the targeted channel runs, such as “+3 ~12 -1 · 4.1 MB → 4.3 MB · devices on 1.4.1 download up to 38.0 KB”.
Options
- `[path]`: Bundle directory. If omitted, the CLI uses OTAKIT_BUILD_DIR or capacitor.config.* webDir.
- `--app-id <id>`: App ID override.
- `--server <url>`: Server URL override.
- `--version <version>`: Version string. Otherwise OTAKIT_VERSION, then auto-generated.
- `--strict-version`: Require explicit or env-provided version.
- `--strict-artifacts`: Fail before uploading when the bundle is very large or contains native installers, .env files, .git or node_modules. Source maps and hidden files are only noted.
- `--release [channel]`: Release after upload. Omit channel to release to the base channel.
- `--strategy <strategy>`: Upload strategy: "zip" (single archive, default) or "deltas" (per-file objects; devices download only what changed).
- `--force-immediate`: With --release: devices apply and reload this release on their next check (emergency fixes).
- `--rollout <percent>`: With --release: release to this share of devices first (1-100, default 100). See Percentage rollouts.
- `--replace-rollout`: With --release: cancel the channel's active rollout and release this bundle in its place.
- `--notes <text>`: With --release: release notes app users may see (plain text, up to 2,000 characters). See Release notes.
- `--notes-file <path>`: With --release: read the release notes from a file.
- `--preview`: Also create a preview link and QR code for the uploaded bundle. See Preview links.
- `--encrypt`: Encrypt the bundle with OTAKIT_ENCRYPTION_KEY before upload (auto-enabled when the env var is set).
- `--fail-on-incompatible`: Exit non-zero when the native compatibility check finds changes that need a store build.
- `--ignore-compat`: Skip the native compatibility check.
Example
```txt
otakit upload --release
```
### otakit release [bundleId]
Release a bundle to the base channel or a named channel. The bundle already carries its runtimeVersion, so release only chooses the rollout channel.
Options
- `--channel <channel>`: Target named channel. Omit it to use the base channel.
- `--force-immediate`: Devices apply and reload this release on their next check (emergency fixes).
- `--rollout <percent>`: Release to this share of devices first (1-100, default 100). The channel needs a previous release.
- `--replace-rollout`: Cancel the channel's active rollout and release this bundle in its place.
- `--notes <text>`: Release notes app users may see (plain text, up to 2,000 characters). Edit them later in the dashboard.
- `--notes-file <path>`: Read the release notes from a file.
Example
```txt
otakit release --channel production --rollout 10
```
### otakit rollout [releaseId]
Show active rollouts, or raise, lower, complete, or cancel one. Without a release ID it acts on the rollout of the selected channel.
Options
- `--channel <channel>`: Channel of the rollout.
- `--base`: The rollout on the base channel.
- `--percent <percent>`: Set the share of devices (1-100; 100 completes the rollout).
- `--complete`: Release to every device.
- `--cancel`: Revert the rolling release; every device returns to the previous release.
Example
```txt
otakit rollout --channel production --percent 50
```
### otakit preview [bundleId]
Create a private link and QR code that open a bundle in the installed app on one phone, without releasing it. Defaults to the latest upload. The app needs previewLinks: true and a custom URL scheme.
Options
- `--expires <duration>`: How long the link works: 1h, 24h, 7d (default) or 30d.
- `--scheme <scheme>`: The app's custom URL scheme, such as myapp. Needed once; the app remembers it.
- `--list`: List active preview links.
- `--revoke <previewId>`: Revoke a preview link.
- `--json`: Print JSON output.
Example
```txt
otakit preview --scheme myapp
```
### otakit compatibility
Check the local native plugin set against a channel's current release without uploading.
Options
- `--channel <channel>`: Channel to compare against. Omit for the base channel.
- `--package-json <path>`: package.json used for native dependency detection.
- `--node-modules <path>`: node_modules used for native dependency detection.
Example
```txt
otakit compatibility --channel production
```
### otakit list
List uploaded bundles.
Options
- `--limit <n>`: Max results. Defaults to 20.
Example
```txt
otakit list --limit 20
```
### otakit diff <bundleId>
Compare a bundle with another: files added, changed and removed, the unpacked size before and after, what devices on the base download (the whole archive for zip updates; at most the content they do not have yet for delta updates), and warnings about content that should not ship. The warnings help catch build mistakes; they are not a security scan. Encrypted bundles cannot be inspected.
Options
- `--against <bundleId>`: Compare with this bundle. Without --against, --channel or --base, the CLI compares with the previous upload of the same runtime version.
- `--channel <channel>`: Compare with the bundle this channel runs.
- `--base`: Compare with the bundle the base channel runs.
- `--json`: Print the comparison as JSON, with up to 5,000 changed files (unlistedChanges counts the rest).
Example
```txt
otakit diff 2ffbb928-96b1-4297-a5b7-c1633c104868 --channel production
```
### otakit releases
Show release history across all streams or a specific target.
Options
- `--channel <channel>`: Show only a named channel.
- `--base`: Show only the base channel.
- `--limit <n>`: Max results. Defaults to 10.
Example
```txt
otakit releases --base
```
### otakit delete <bundleId>
Delete a bundle.
Options
- `--force`: Skip confirmation prompt.
Example
```txt
otakit delete abc123 --force
```
### otakit register
Create a new app and print the plugin snippet to paste into capacitor.config.ts.
Options
- `--slug <slug>`: App slug (for example com.example.app).
- `--server <url>`: Server URL override.
- `--token <token>`: Access token or organization API key.
- `--secret-key <key>`: Alias for --token.
Example
```txt
otakit register --slug com.example.myapp
```
### otakit login
Sign in with email OTP and store a token locally.
Options
- `--email <email>`: Email address. If omitted, prompts interactively.
- `--server <url>`: Server URL override.
- `--token-only`: Print token to stdout only.
Example
```txt
otakit login --email you@example.com
```
### otakit whoami
Show current authenticated user and organization context.
Options
- `--server <url>`: Server URL override.
- `--json`: Print machine-readable account and organization details.
Example
```txt
otakit whoami
```
### otakit organization select
Choose the default organization for commands not tied to an app. Configured apps always use their owning organization.
Options
- `--server <url>`: Server URL override.
Example
```txt
otakit organization select
```
### otakit logout
Remove stored token for a server.
Options
- `--server <url>`: Server URL override.
Example
```txt
otakit logout
```
### otakit config resolve
Show effective CLI values and where they came from.
Options
- `--app-id <id>`: App ID override.
- `--server <url>`: Server URL override.
- `--output-dir <path>`: Output directory override.
- `--channel <channel>`: Channel override.
- `--json`: Print machine-readable JSON output.
Example
```txt
otakit config resolve --json
```
### otakit connect
Connect this project to your coding agent. Signs in if needed, then writes the client's MCP configuration after showing exactly what it resolved and what it will write.
Options
- `--client <client>`: claude, codex, or vscode. Defaults to detected.
- `--project-root <path>`: Project to connect. Defaults to the current directory.
- `--server <url>`: OtaKit console URL override.
- `--dry-run`: Show the plan and exit without writing.
- `--yes`: Skip the confirmation prompt.
Example
```txt
npx -y @otakit/cli@latest connect
```
### otakit push send
Send a push notification to your app users. Needs the Push notifications add-on (Settings → Add-ons) and an APNs key and/or Firebase service account for the app. Shows the audience size and asks before sending.
Options
- `--title <title>`: Notification title (required).
- `--body <body>`: Notification text (required).
- `--url <url>`: Path or https link the app opens, sent as data.url.
- `--data <key=value>`: Extra data for the app (repeatable).
- `--platform <platform>`: ios or android (repeatable; default both).
- `--channel <channel>`: Only devices on this OTA channel (repeatable).
- `--topic <topic>`: Only devices subscribed to this topic (repeatable).
- `--user <id>`: Only devices of this user ID (repeatable).
- `--yes`: Send without the confirmation prompt (required in CI).
- `--json`: Print the campaign as JSON.
Example
```txt
otakit push send --title "New drop" --body "Open the app to see it" --url /shop --topic news
```
### otakit push campaigns
List recent push campaigns with delivery counts.
Options
- `--limit <n>`: Number of campaigns (default 10, max 100).
- `--json`: Print machine-readable JSON output.
Example
```txt
otakit push campaigns
```
### otakit push campaign <campaignId>
Show one campaign: status, devices targeted and accepted by Apple/Google, failures and removed tokens.
Options
- `--json`: Print machine-readable JSON output.
Example
```txt
otakit push campaign 11dead02-8f6f-4349-8ea3-7667c2a4382c
```
### otakit mcp
Start the local MCP server, bound to one project and organization for its lifetime.
Options
- `--project-root <path>`: Project root available to local MCP tools.
- `--organization-id <id>`: Advanced organization override for app-less automation.
Example
```txt
npx -y @otakit/cli@latest mcp --project-root .
```
### otakit config validate
Validate the OtaKit-related values in capacitor.config.*.
Options
- `--json`: Print machine-readable JSON output.
Example
```txt
otakit config validate
```
### otakit generate-signing-key
Generate an ES256 key pair for manifest signing.
Example
```txt
otakit generate-signing-key
```
### otakit generate-encryption-key
Generate an AES-256 bundle encryption key. Keep it in CI as OTAKIT_ENCRYPTION_KEY and ship it in the app's bundleKeys config.
Example
```txt
otakit generate-encryption-key
```
### Troubleshooting
- Missing app ID: add `plugins.OtaKit.appId` to `capacitor.config.ts`, or pass `--app-id`.
- Missing `index.html`: build your web app and verify `webDir` or the explicit upload path.
- Need to create an app from automation: use `otakit register --slug <slug>`.
## Plugin API
Route: /docs/plugin
Capacitor plugin setup, policy-based automatic updates, and manual advanced flows.
Import from `@otakit/capacitor-updater`. The default flow usually only needs `notifyAppReady()`. The other public methods exist for advanced manual update flows whe