Installation

Install the oxagen CLI from the monorepo, as a portable single-file bundle, or from npm.

The oxagen CLI requires Node.js 20 or newer. Check your version with node --version.

There are three ways to get it. If you just want to try it on your own machine, build from the monorepo. If you need a portable binary for CI or a container, build the standalone bundle.

From the monorepo (recommended today)

Clone the repo, install dependencies, and run the CLI directly from source:

git clone https://github.com/oxagen/oxagen-monorepo.git
cd oxagen-monorepo
pnpm install

# Run straight from source (TypeScript via tsx):
pnpm --filter @oxagen/cli start -- --version

# …or compile once and run the built output:
pnpm --filter @oxagen/cli build
node apps/cli/dist/index.js --version

To get a short oxagen command, alias it in your shell profile (~/.zshrc, ~/.bashrc):

alias oxagen='pnpm --filter @oxagen/cli start --'
# then:  oxagen "explain the auth flow in this repo"

Standalone bundle (portable, no install)

For CI runners, ephemeral containers, or putting oxagen on your PATH without a global npm install, build a self-contained single-file bundle. It runs under plain node with no workspace resolution and no npm install step:

pnpm --filter @oxagen/cli bundle
# → apps/cli/dist-standalone/oxagen.mjs  (executable, Node 20+)

node apps/cli/dist-standalone/oxagen.mjs --version

The bundle is one .mjs file. Copy it anywhere and run it, or symlink it onto your PATH:

ln -s "$(pwd)/apps/cli/dist-standalone/oxagen.mjs" /usr/local/bin/oxagen
oxagen --version

The bundle leaves two optional native dependencies (duckdb, blake3) external. If they are not present in the runtime environment the CLI still runs the full agent loop — it just skips persistent on-disk memory and the local graph replica. Install them in the same environment if you want those features.

From npm

@oxagen/cli is published to npm:

npm install -g @oxagen/cli
# or
pnpm add -g @oxagen/cli

oxagen --version

The published package is not yet fully standalone-installable in a clean environment: it carries internal workspace dependencies and its launcher expects tsx on the PATH, so a bare npm i -g can fail outside the monorepo. Until that is resolved, prefer the monorepo or standalone bundle methods above for a reliable install. A self-contained npm package is in progress.

Verify the install

Whichever method you used, confirm the binary works and see the top-level help:

oxagen --version
oxagen --help

oxagen --help lists every command group. You can append --help to any command (e.g. oxagen graph pull --help) for its flags.

Next step

With the binary in place, set up your Oxagen account and authenticate the CLI.