Quick Start

Install CLI

npm install -g opkg

Install packages

# From local/remote registry or local path
opkg install <package-name-or-path>

# From GitHub repo or Claude Code Marketplace/Plugin
opkg install github:<username>/<repo>
# or
opkg install git:<url>.git

Use the install command to install all files from the package into the codebase at cwd, formatted and converted to per platform conventions and into their respective dirs. See install for more details and options.

Uninstall packages

opkg uninstall <package-name>

Use the uninstall command to remove all files for the package from the codebase at cwd. See uninstall for more details and options.

Create a package

opkg new <package-name>

Compose package

Manually add/update/remove files to and from the package following this structure:

<package>
│   
│   # Package files
├── openpackage.yml       # The OpenPackage manifest, required
├── README.md             # LICENSE.md, CONTRIBUTING.md, etc.
│   
│   # Content files
├── rules/                # Rule files
├── commands/             # Command files (slash commands)
├── agents/               # Agent files (subagents)
├── skills/               # Skill files (skills)
├── root/                 # Any other root dirs or files (Ex: specs/, docs/, tests/, etc.)
├── AGENTS.md             # Platform root file
├── mcp.jsonc             # MCP config file
│   
│   # Custom files
└── <other>               # Customizable via `platforms.jsonc` overrides/extensions

There are a few helpful commands that you can use to help you with composition:

Add

Copies dirs or files from a workspace over to the package. See add for detailed usage and more ways to use the add command.

opkg add <package-name> <path-to-dir-or-file>

# Example
opkg add essentials .cursor/rules/essentials
opkg add essentials .cursor/rules/essentials-overview.md
opkg add essentials .cursor/commands/essentials

Remove

Removes dirs or files from the package. See remove for detailed usage and more ways to use the remove command.

opkg rm <package-name> <path-to-dir-or-file>

# Example
opkg rm essentials .cursor/rules/essentials
opkg rm essentials .cursor/rules/essentials-overview.md
opkg rm essentials .cursor/commands/essentials

Applying package changes

opkg apply <package-name>

Use the apply command to perform file content sync from package to workspace (similar to install but for already installed packages). You can also use this command to sync package content to new platforms. See apply for detailed usage and more ways to use the apply command.

Saving workspace changes

opkg save <package-name>

You can directly update the files that belong to packages in your workspace, then run save to sync these changes back to the package. See save for detailed usage and more ways to use the save command.

Packing packages

opkg pack <package-name>

Packages are unversioned by default and installs files as is from the package source. To store individual stable versions, you can use the pack command to snapshot packages per version. Your snapshots will be stored to your local machine under the ~/.openpackage/registry/ dir. See pack for detailed usage and more ways to use the pack command.

List packages

opkg list

Use the list command to show all packages currently saved to the local registry at ~/.openpackage/registry/. See list for more details and options.

Show package details

opkg show <package-name>

The show command outputs the details of the package and lists all included files. See show for more details.

Push a package to remote

opkg push <package-name>

Use the push command to upload a package to the official OpenPackage registry. See push for more details, see configure to setup auth with api keys.

Pull a package from remote

opkg pull <package-name>

Use the pull command to download a package from the official OpenPackage registry to the local registry. See pull for more details, see configure to setup auth with api keys.