RavenJS CLI

The RavenJS CLI is designed for Agent consumption. AI skills (raven-setup, raven-learn, raven-use, raven-update) invoke it via bunx raven. To get skills into your project, use install-raven (e.g. npx install-raven); then run bunx raven init to create the raven root and install the managed core tree, or let raven-setup do it.

Install (project-local, recommended). Requires Bun >=1.0:

bun add -d @raven.js/cli

Commands

| Command | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | bunx raven init | Initialize the Raven root, write raven.yaml, and install the managed core/ reference tree. | | bunx raven sync | Rebuild the managed core/ tree from the embedded source, removing legacy module dirs atomically. Requires a Git worktree and clean managed Raven paths. | | bunx raven status | Show RavenJS installation status for the single managed core tree. Output is JSON for Agent consumption. |

Options

| Option | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------- | | --root <dir> | RavenJS root directory (default: raven). Overridable via RAVEN_ROOT. | | --registry <path> | Path to embedded-source manifest JSON (default: same dir as CLI). Overridable via RAVEN_DEFAULT_REGISTRY_PATH. | | --verbose, -v | Verbose output. |

Offline behavior

The CLI embeds the managed core source at build time (dist/source/core/). raven init and raven sync read only from this embedded source and do not perform network requests.

OpenAPI exposure now lives in the Raven app runtime. Configure it from your app composition root with app.exportOpenAPI(...) instead of using a CLI build step.

Recommended update flow

Use the raven-update skill as the default RavenJS upgrade entry point:

1. Verify the Git worktree is clean before starting the upgrade
2. bun add -d @raven.js/cli@latest
3. bunx raven sync
4. Analyze the resulting Git diff and adapt project code if the update introduces breaking changes

The skill performs this flow for the Agent and enforces the safety checks in the right order.

Sync semantics

raven sync treats <root>/core/ as CLI-managed Raven assets. It recreates the managed directory from the embedded source, removes files that no longer exist in the embedded source, removes legacy top-level module directories such as sql/, and swaps the rebuilt root into place only after staging succeeds.

raven sync refuses to run unless the current directory is inside a Git worktree and the managed Raven paths are clean. The protected paths are <root>/raven.yaml, <root>/core/, and legacy managed directories that sync will delete. Unrelated repo edits such as package.json, lockfiles, app source, or passthrough files under <root>/ do not block sync.