---
title: CLI Command Reference
description: Understand command syntax, global options, output formats, and the complete Octarine CLI reference.
---

The Octarine CLI uses the form `octarine [global options] <command> [command options]`. Every public command is documented in this section with its syntax, behavior, and at least one example.

## Choose A Command Area

| Area | Commands |
| --- | --- |
| [Workspaces and search](/cli/workspaces-and-search) | `workspace`, `search` |
| [Notes](/cli/notes) | `note create`, `read`, `context`, targeted edits, tasks, and every other note operation |
| [Folders, links, and tasks](/cli/folders-links-and-tasks) | `folder`, `link`, workspace-wide `task` and `tag` |
| [Properties and resources](/cli/properties-and-resources) | `property`, `metadata`, `view`, `note-type`, `theme` |
| [Inbox](/cli/inbox) | Capture, promote, snooze, tag, resolve, and diagnose Inbox items |
| [Agents and MCP](/cli/agents-and-mcp) | `agent-guide`, `help --json`, `mcp` |
| [Automation and maintenance](/cli/automation-and-maintenance) | Output formats, errors, `config`, `schema`, `export`, `capabilities`, `doctor`, `completion`, `update` |

## Global Options

Global options can appear before or after a subcommand.

| Option | Purpose |
| --- | --- |
| `--workspace <name, uuid, or path>` | Select a workspace. Also available as `OCTARINE_WORKSPACE`. |
| `--app-store <path>` | Override the desktop workspace registry. Also available as `OCTARINE_APP_STORE`. |
| `--database <path>` | Override the shared SQLite database. Also available as `OCTARINE_DATABASE`. |
| `--json` | Emit one stable JSON envelope. |
| `--jsonl` | Emit one JSON object per result. |
| `--format <table, plain, json, or jsonl>` | Select an output format explicitly. Also available as `OCTARINE_FORMAT`. |
| `--fields <a,b,c>` | Project selected fields from object or array output. |
| `--request-id <id>` | Echo a caller-provided ID in machine-readable response metadata. |
| `--quiet` | Suppress non-essential output. |
| `--verbose` | Reserved for diagnostic output. Currently has no effect. |
| `--no-color` | Disable ANSI styling. `NO_COLOR` is also honored. |
| `--no-progress` | Reserved for disabling progress indicators. Currently has no effect. |
| `--non-interactive` | Reject prompts rather than waiting for input. Only `update` prompts today. |

```bash
octarine --workspace "Work Notes" note list
octarine note list --workspace ~/Notes --json
octarine search launch --fields path,line,text --format jsonl
```

`--json`, `--jsonl`, and `--format` are alternative output selectors. Do not combine them.

Without an output option, the CLI uses `OCTARINE_FORMAT`, then the `format` setting from [`octarine config`](/cli/getting-started#set-defaults). If none is set, it prints tables in a terminal and tab-separated `plain` output when piped to another program.

## Workspace Paths

Paths such as `Projects/Launch.md` are relative to the selected workspace. Quote names containing spaces. The CLI rejects traversal and symlink paths that escape the workspace.

```bash
octarine --workspace ~/Notes note read "Projects/Launch plan.md"
```

Workspace selection follows this order:

1. `--workspace`
2. `OCTARINE_WORKSPACE`
3. The nearest parent containing `.octarine`
4. The default saved with `octarine workspace use`
5. The sole workspace in the desktop app registry

## Get Exact Installed Syntax

The installed executable is authoritative when versions differ from these docs.

```bash
octarine --version
octarine --help
octarine note --help
octarine note create --help
octarine help note edit --json
```

`help --json` describes every command, argument, output envelope, and error code in machine-readable form. See [Agents and MCP](/cli/agents-and-mcp).

Workspace registration, renaming, removal, and deletion are intentionally not public CLI operations. `workspace use` only changes the CLI's default workspace. The desktop app owns those registry mutations.