How do I start an Offline Protocol project with the CLI?

The Offline Protocol CLI is the npm package @offline-protocol/cli, and it installs a command named offline. It needs Node.js 18 or later and ships prebuilt binaries for macOS (arm64 and x64), Linux (x64 and arm64) and Windows (x64).

npm install -g @offline-protocol/cli
offline --version

The npm package is a small Node.js launcher. npm installs only the native binary for your machine, from a per-platform optional dependency such as @offline-protocol/cli-darwin-arm64, so an install downloads about 10 MB rather than all five binaries. Keep optional dependencies enabled: installing with --omit=optional or --no-optional leaves you without the binary.

To run a command without a global install, prefix it with npx:

npx -y @offline-protocol/cli --version

offline update asks the npm registry for a newer release and prints the upgrade command; it does not install it. The CLI is licensed Apache-2.0, separately from the AGPL-3.0-only SDK.

The fastest start is offline plan, which takes a description of what you are building and recommends a workflow, the packages it needs and the exact offline create command. Three workflows cover common integrations, and each scaffolds a React Native app with no login:

offline create --template offers three starter apps, orderup, stocksync and cowrite. Useful flags include --dir <dir> to write somewhere other than ./<name>, -y to run without prompts, and --pol to add Proof of Location to a React Native scaffold. offline registry list workflows and offline registry list templates show everything available, and offline add <package> --dry-run prints what adding a package would change without writing files. Scaffolding runs npm install, which contacts the registries you have configured. The workflows themselves are explained in the docs’ local handoff, backend delivery and nearby service guides.

The registry also covers the bindings beyond React Native, including Java, the C API and the Flutter preview, and Flutter and Java prompts are answered with that package rather than a React Native plan. To compare them yourself, see which Offline Protocol SDK to use.

offline init adds Offline Protocol configuration to an existing JavaScript or TypeScript project. Run it from a directory that contains package.json; for a new application, use offline create instead.

offline init --app-id app_your_application_id

It writes offline.config.json, an AGENTS.md section and, when the project has none, a .mcp.json that starts the local MCP server through npx. The App ID is public metadata from the developer portal, so it can live in these files; API keys should not. Review the generated changes with the rest of your code. There is no offline link command, and initialization takes --app-id, not --project-id.

You only need to sign in when you want an API key or want to manage portal resources from the terminal. offline login prints a confirmation code and opens https://dev.offlineprotocol.com/cli-auth, where you choose the application, enter the code and approve. Each login creates a new app API key for that terminal; organization keys are not accepted.

offline login            # opens the developer portal in your browser
offline login --email    # email code sign-in in the terminal
offline whoami

offline login --no-browser suits a headless machine, with approval from another browser. offline login --email stores a developer session instead of an API key, and the setup, orgs, apps and keys commands need it. That session lasts 30 days, renews while you use the CLI, and ends 90 days after sign-in at the latest. offline whoami --verify checks the stored key and App ID against the developer API, and offline logout clears local credentials and revokes the key that login created.

Signing in writes ~/.offline/config.json (or $OFFLINE_CONFIG_DIR/config.json): the app API key, the developer session token from email sign-in, your email address, and your developer, organization and application IDs. The file is plain JSON, not encrypted and not in the system keychain. On macOS and Linux it is created owner-only (0600) inside an owner-only directory; on Windows it keeps your profile folder’s default permissions. Anyone who can read the file can use the key.

The CLI sends sign-in requests, including your computer’s hostname as the device name you see when approving, and the developer API calls each command makes. offline update contacts the npm registry only when you run it. The CLI and the local MCP server send no usage analytics and no crash reports.

The CLI also contains the Offline Protocol MCP server, which gives a coding agent the same registry, guidance and scaffolding tools. It runs over standard input and output and needs no login or API key:

npx -y @offline-protocol/cli@0.2.9 mcp serve

Once the CLI is installed globally, offline mcp serve starts the same server and offline mcp tools lists its tools. offline mcp install <client> prints configuration for claude-code, claude-desktop, codex, cursor or vscode; it does not edit your client’s files. Its output starts the server with offline mcp serve, so it needs the offline command on the PATH your client uses. What is the Offline Protocol MCP server? covers the local and hosted modes, and Claude and Cursor each have a setup article.

These are the commands in CLI 0.2.9. offline <command> --help shows each one’s options.

OFFLINE_APP_ID and OFFLINE_ORG_ID override the IDs saved in config.json when no flag is passed. Each CLI release pins the SDK release it was tested with, so scaffolds are repeatable. From the scaffold, you build the app and run it on your devices.