Setup

Install UluOps into Claude Code, OpenCode, Gemini CLI, or Codex — one command, every harness on your machine in a single run.

One Command

npx @uluops/setup

That's it. The installer detects your agentic harness and configures it with MCP servers, validation agents, and slash commands. If you already have an API key set via ULUOPS_API_KEY or saved in ~/.uluops/credentials.json, setup will use it automatically.

The default target is Claude Code. To install into a different harness, pass --harness:

npx @uluops/setup --harness opencode
npx @uluops/setup --harness gemini-cli
npx @uluops/setup --harness codex   # experimental

Your API key

Setup authenticates with a UluOps API key. The first thing it asks is whether you are creating a new account:

• Yes — you are prompted for an email and password; the installer creates the account, mints a key, saves it to ~/.uluops/credentials.json, and continues. --signup skips the question and goes straight there.
• No — you paste an existing key. Keys start with ulr_; the installer verifies it against the API before continuing (--skip-validation to bypass).

The question is skipped automatically when a key is already in ULUOPS_API_KEY, in ~/.uluops/credentials.json, or passed with --api-key.

Where to get a key

1. Dashboard — sign in at app.uluops.ai, open Settings → API keys, click Create Key, give it a name and a scope (write for setup, the CLI and MCP servers; read for dashboards and reporting). The key is shown once — copy it before closing the dialog. You can revoke or rotate it from the same page.

2. CLI — if you already have an account and @uluops/cli installed:

   bashCopy

   ulu auth login                                        # email + password
   ulu auth api-keys create --name "laptop" --scope write

3. Setup itself — npx @uluops/setup --signup creates the account and the key in one go, no browser needed.

Then either paste the key when setup asks, or pass it in:

npx @uluops/setup --api-key ulr_...
# or
ULUOPS_API_KEY=ulr_... npx @uluops/setup

--shell also writes an export ULUOPS_API_KEY=... line to your shell profile so ulu and the SDKs find it in every new terminal. Keys are secrets: never commit one, and rotate it if it leaks.

Multi-Harness Install

Run multiple agentic harnesses on the same machine? Install UluOps into all of them in one invocation — no need to re-run setup for each:

# Install into every harness we detect on your machine
npx @uluops/setup --all-detected

# Install into a specific subset (comma-separated)
npx @uluops/setup --harness claude-code,gemini-cli

# Same thing, alternative form (--all-detected is the canonical name)
npx @uluops/setup --harness all

When you have multiple harnesses installed, an interactive run presents a checkbox prompt with every detected harness checked by default — press Enter to install everywhere, or use space to toggle off the ones you want to skip.

The summary tells you exactly what landed:

  Setup complete: 3 installed of 3 harnesses

  ✓ [Claude Code] installed (23 agents · 28 commands · metrics)
  ✓ [OpenCode] installed (23 agents)
  ✓ [Gemini CLI] installed (23 agents · 28 commands · metrics)

  Restart each of Claude Code, OpenCode, Gemini CLI to load agents.

Failure isolation: if one harness fails (permission error, broken config, etc.), the others still install. The failing one is marked with a ✗ icon, a clear error, and a Re-run: npx @uluops/setup --harness <name> hint so you can retry just that one.

CI scripts: to keep automation predictable, non-interactive runs (--yes, --api-key, piped stdin) install into the first detected harness only and surface a notice listing the others. CI users who want multi-install opt in explicitly with --all-detected.

Supported Harnesses

Auto-detection skips experimental harnesses — Codex only installs when you ask for it explicitly.

What Gets Installed

The two MCP servers — uluops-tracker and uluops-registry — give your harness native access to UluOps tools for tracking runs, managing issues, querying analytics, and working with agent definitions.

Paths differ per harness: OpenCode installs to ~/.config/opencode/, Gemini CLI to ~/.gemini/, Codex to ~/.codex/. Agent definitions and commands are transformed to each harness's native format at install time from a single source.

Verify Your Installation

npx @uluops/setup --verify

This checks that all files are in place, MCP servers are configured, the API is reachable, and — if a previous install hit a partial-state error — surfaces a warning so you know a re-run is needed to complete.

Uninstall

# Remove everything: every harness in the manifest + globals + shell export
npx @uluops/setup --uninstall

# Remove UluOps from a specific harness only — others preserved
npx @uluops/setup --uninstall --harness opencode

# Remove from a subset
npx @uluops/setup --uninstall --harness opencode,gemini-cli

Subset uninstall preserves the global @uluops/cli install, @uluops/agent-metrics, and your shell-profile export — they may still serve the remaining harnesses. The manifest is updated rather than deleted. A subset uninstall that names a harness not in the manifest fails fast with an error listing what IS installed, so you can correct typos.

Removed: agent files, command files, MCP config entries, metrics hook. Preserved: custom agents you added yourself, non-UluOps MCP servers, and any user-installed @uluops/cli (only the globals this installer installed are removed).

Try It

Once your harness restarts, run your first validation on a repo you own:

/agents:validate .

Then read what it found and what you decided about it:

ulu log

Or run a full workflow:

/pipelines:post-implementation

Options

--harness <name> --all-detected is a conflict — pass one or the other.

Updating

Re-running npx @uluops/setup is safe at any time. The installer is idempotent — it uses content hashes to skip unchanged files, updates only what's new, and removes artifacts that are no longer in the current version. The manifest supports multiple harnesses, so installing into a new harness after the fact just adds a sibling entry; previously-installed harnesses are reconciled in place.

Next Steps

• Quickstart — Run your first agent in Claude Code (and use the SDK to save runs programmatically)
• Run a Validation — Deeper guide on workflows and agents
• Definitions — How agents are defined