Reference

CLI Reference

Complete reference for every oxp subcommand with flags, examples, and environment variables.

The oxp CLI is the primary tool for creating, developing, packing, and publishing OXP extensions. It ships as a single npm package with no external dependencies.

Installation

bash

npm i -g @oxprotocol/cli
pnpm add -g @oxprotocol/cli

Global Options

Flag	Description
`--help`, `-h`	Show help
`--version`, `-v`	Print version

Environment Variables

Variable	Default	Description
`OXP_REGISTRY`	`https://oxp.sh`	Registry base URL
`OXP_HOME`	`~/.oxp`	Config + credentials directory
`OXP_DEV_PORT`	`7373`	Default port for `oxp dev`

Commands

`oxp create`

Scaffold a new extension from a template.

bash

oxp create <name>
oxp create -t hello-tree <name>
oxp create --template hello-rust <name>
oxp create --list-templates

Flag	Description
`-t`, `--template <name>`	Template to use (default: `hello-html`)
`--list-templates`	List available templates and exit

Templates: hello-html, hello-code, hello-tree, hello-rust

The publisher field is derived from your OS username. The slug is the project name lowercased.

`oxp dev`

Watch a project, re-pack on changes, and serve over WebSocket + HTTP for hot-reload.

bash

oxp dev
oxp dev --port 8080
oxp dev ./my-extension

Flag	Description
`-p`, `--port <n>`	Server port (default: 7373)

Endpoints served:

ws://localhost:<port>/dev — WebSocket reload channel
GET /info — manifest, digest, size
GET /manifest — raw oxp.json
GET /bundle — raw .oxp bytes

Dev mode skips Ed25519 signing. Connected hosts show a "DEV" badge.

`oxp pack`

Build a deterministic, signed .oxp bundle.

bash

oxp pack
oxp pack ./my-extension

Output: dist/<slug>-<version>.oxp

The pack pipeline: validate manifest → enforce bundle policy → tar+zstd → hash → sign → write.

`oxp login`

Authenticate with the registry.

bash

oxp login              # email + password in terminal
oxp login --browser    # OAuth device flow via browser

Tokens stored at ~/.oxp/credentials (mode 0600).

`oxp publish`

Upload a signed bundle to the registry.

bash

oxp publish
oxp publish dist/my-ext-1.0.0.oxp

Requires authentication (oxp login) and a signing key (oxp keygen).

`oxp install`

Install an extension from the registry.

bash

oxp install @publisher/slug
oxp install @publisher/slug -y           # skip confirmation
oxp install @publisher/slug --json       # machine-readable output
oxp install --from oxp://publisher/slug  # from deep link

Flag	Description
`-y`	Auto-accept permission prompts
`--json`	Output in JSON format
`--from <url>`	Install from an `oxp://` deep link

The install pipeline: resolve version → download → verify signature → verify digest → extract → verify per-file integrity → permission prompt → detect IDEs → install host wrappers.

`oxp keygen`

Print the local Ed25519 publisher key ID, creating a new keypair if needed.

bash

oxp keygen
# → ed25519:0xABCD1234...

`oxp token rotate`

Mint a successor API token; the old token gets a 5-minute grace window.

bash

oxp token rotate
oxp token rotate --days 90
oxp token rotate --name "CI token"
oxp token rotate --scope "publish:@acme/*"

Flag	Description
`--days <n>`	Token lifetime (default: 90)
`--name <label>`	Human-readable token label
`--scope <scope>`	Token scope (e.g. `publish:@acme/*`)

`oxp protocol-register`

bash

oxp protocol-register

Programmatic Use

All subcommands are exported as functions:

typescript

import { create, pack, publish } from "@oxprotocol/cli";

const code = await create(["my-ext", "-t", "hello-rust"]);