nodus 0.10.1

Local-first CLI for managing project-scoped agent packages.
Documentation

What Is Nodus?

Nodus is a package manager for repo-scoped agent tooling.

If a package publishes content such as skills/, agents/, rules/, or commands/, Nodus can:

  • add it from GitHub, Git, or a local path
  • record what you asked for in nodus.toml
  • lock the exact resolved revision in nodus.lock
  • write managed files into adapter roots such as .codex/, .claude/, .cursor/, .github/, .agents/, or .opencode/
  • compose managed MCP server config for supported runtimes, including .mcp.json, .codex/config.toml, and opencode.json
  • prune stale generated files without touching unmanaged ones

For most teams, the normal flow is:

nodus add <package> --adapter <adapter>
nodus doctor

Install

Install from crates.io:

cargo install nodus

Building from source requires Rust 1.88.0 or newer.

Install the latest prebuilt binary on macOS or Linux:

curl -fsSL https://nodus.elata.ai/install.sh | bash

Install with Homebrew:

brew install nodus-rs/nodus/nodus

Install the latest prebuilt binary on Windows with PowerShell:

irm https://nodus.elata.ai/install.ps1 | iex

If the command fails, install PowerShell 7, restart your terminal, then run:

winget install --id Microsoft.PowerShell --source winget
pwsh -NoProfile -Command "irm https://nodus.elata.ai/install.ps1 | iex"

For AI Assistants

If you want an AI assistant to operate Nodus for you, give it the fetchable prompt URL:

That prompt gives the assistant concrete Nodus operating instructions, helps it choose the right nodus add command, and still ends with nodus doctor.

Quick Start

Install a package into the current repo and verify the result:

nodus add nodus-rs/nodus --adapter codex
nodus doctor

That flow:

  • creates nodus.toml if the repo does not have one yet
  • records the dependency in nodus.toml
  • resolves and locks the exact revision in nodus.lock
  • writes the managed runtime files for the selected or detected adapter

If the package publishes mcp_servers, Nodus now carries that MCP config into the repo's managed runtime outputs as well. Today that includes the legacy project .mcp.json, Codex .codex/config.toml, and OpenCode opencode.json.

If the package is a wrapper that exposes multiple child packages, nodus add now records the wrapper itself and leaves child packages disabled until you either edit members in nodus.toml or opt in up front with --accept-all-dependencies.

If you want a user-level install instead of repo-scoped state, use --global explicitly:

nodus add nodus-rs/nodus --global --adapter codex

CLI Help

nodus --help is the main command guide.

Start there when you want to learn the workflow, then open command-specific help as needed:

nodus --help
nodus add --help
nodus sync --help
nodus doctor --help

Commands most users need:

  • nodus add <package> --adapter <adapter> to install a package into the current repo
  • nodus info <package-or-alias> to inspect a package before or after install
  • nodus sync to rebuild managed outputs from the versions already recorded
  • nodus update to move dependencies to newer allowed revisions
  • nodus remove <alias> to remove a dependency and prune what it owned
  • nodus clean to clear shared repository, checkout, and snapshot cache data without changing project manifests or managed outputs
  • nodus doctor to check that the repo, lockfile, shared store, and managed outputs still agree

Learn More

For package authoring details, workspace packaging, managed exports, or relay workflows, prefer the website docs and nodus --help over treating this README as the full command reference. That applies to MCP packages too: package authors can publish mcp_servers in nodus.toml, and consumers get the matching managed project config for the adapter they use.

Contributing

See CONTRIBUTING.md for local development and release checks.

License

Licensed under Apache-2.0.