# OX CLI Reference

> **Scope:** This reference covers the **Go CLI** (v0.3.0). For the Rust implementation's CLI, see [Two Implementations](https://iamox.ai/docs/two-implementations.md).

`ox` is a CLI tool for bootstrapping and managing OX workspaces. One binary, every platform, zero dependencies.

```
Usage:
  ox [command]
```

## Commands

| Command | Description |
|---------|-------------|
| `ox init` | Initialize a new ox workspace on this machine |
| `ox clone [org]` | Clone or update all repos for a GitHub organization |
| `ox index` | Index the knowledge base and code for search and graph queries |
| `ox search <query>` | Search using hybrid text + vector search |
| `ox serve` | Start the MCP server for AI agent integration |
| `ox status` | Show workspace health and status |
| `ox kb` | Manage knowledge bases (create, info, list, switch) |
| `ox workspace` | Start the ox workspace web UI |
| `ox version` | Print the ox version |
| `ox completion` | Generate a shell autocompletion script |

Run `ox [command] --help` for details on any command.

## ox init

Creates the directory structure, installs CLI dependencies, authenticates with GitHub, clones organization repos, and configures MCP servers. See [Installation](https://iamox.ai/docs/installation.md) for the full flag list.

## ox clone

```bash
ox clone [org] [--parallel N]
```

Clones all non-archived repos for a GitHub organization into `x/code/remote/github/<org>/`. Existing repos are skipped (not force-updated).

## ox index

```bash
ox index [flags]
```

Parses all Markdown notes and code repositories, builds a knowledge graph, generates embeddings, and creates full-text search indexes. By default indexes **both** the knowledge base (`o/o/`) and code repos (`x/code/`). Incremental by default via SHA-256 content hashing.

| Flag | Purpose |
|------|---------|
| `--kb-only` | Only index the knowledge base |
| `--code-only` | Only index code repos |
| `--full` | Force a full re-index (ignore the content-hash cache) |
| `--no-embed` | Skip embedding generation (no Ollama needed) |
| `--model` | Embedding model (default `nomic-embed-text`) |
| `--ollama-url` | Ollama API URL (default `http://localhost:11434`) |

## ox search

```bash
ox search <query> [-n LIMIT] [--text-only]
```

Combines BM25 full-text search with semantic vector similarity for ranked results across knowledge **and** code.

| Flag | Purpose |
|------|---------|
| `-n, --limit` | Maximum results (default 20) |
| `--text-only` | BM25 text search only (no embeddings) |

## ox serve

```bash
ox serve [flags]
```

Starts a Model Context Protocol (MCP) server on stdio, exposing knowledge-base search and graph tools to Claude Code and other MCP clients. Add to `.mcp.json` to auto-connect:

```json
{ "ox": { "type": "stdio", "command": "ox", "args": ["serve"] } }
```

| Flag | Purpose |
|------|---------|
| `--no-embed` | Disable embeddings; use BM25 + graph only (no Ollama required) |

See [MCP Server](https://iamox.ai/docs/mcp-server.md).

## ox kb

Manage one or more knowledge bases (directories of Markdown using the who/what/when/where convention). Subcommands: `create`, `info`, `list`, `switch`. Use any editor — Obsidian, VS Code, or the ox web UI.

## ox status

Shows workspace health and status — note counts, indexed repos, and configuration state.