---
title: CLI Setup and Updates
description: Install, configure, and independently update the Octarine command-line interface.
---

The Octarine CLI is a standalone `octarine` executable for working with local Octarine workspaces from a terminal, script, or coding agent. The desktop app does not need to be running, and installing the desktop app does not automatically install the CLI on your `PATH`.

CLI releases are versioned separately from desktop releases. Octarine can therefore ship CLI fixes and features without publishing a new desktop build.

## Supported Platforms

Native CLI archives are published for:

- macOS on Apple Silicon (`aarch64-apple-darwin`)
- Linux on x86-64 (`x86_64-unknown-linux-gnu`)
- Windows on x86-64 (`x86_64-pc-windows-msvc`)

Intel Macs are not supported yet.

Each release includes SHA-256 checksums, an SPDX SBOM, and signatures.

## Install The CLI

On macOS or Linux, run:

```bash
curl -fsSL https://octarine.app/releases/cli/install.sh | sh
```

On Windows, run in PowerShell:

```powershell
irm https://octarine.app/releases/cli/install.ps1 | iex
```

The script downloads the latest CLI release for your platform, checks it against the release's `SHA256SUMS`, and installs it to a user-writable directory:

| Platform | Install directory |
| --- | --- |
| macOS and Linux | `~/.local/bin` |
| Windows | `%LOCALAPPDATA%\Programs\octarine-cli\bin` |

On Windows, the script adds that directory to your user `PATH`; restart open terminals to pick it up. On macOS and Linux, the script prints the line to add to your shell profile if `~/.local/bin` is not already on your `PATH`.

Set either variable before running the script to change its behavior:

| Variable | Purpose |
| --- | --- |
| `OCTARINE_VERSION` | Install a specific version, such as `0.2.0`, instead of the latest release. |
| `OCTARINE_INSTALL_DIR` | Install to another directory. It must stay writable by your user so `octarine update` can replace the executable. |

```bash
curl -fsSL https://octarine.app/releases/cli/install.sh | OCTARINE_VERSION=0.1.0 sh
```

Confirm the installation:

```bash
octarine --version
octarine --help
```

### Install An Archive Manually

You can also download an archive yourself. Release files are published at `https://octarine.app/releases/cli/<version>/`, and `https://octarine.app/releases/cli/latest.txt` holds the latest version number.

On macOS or Linux, download and extract the archive, then place the executable in a directory on your `PATH`:

```bash
VERSION=$(curl -fsSL https://octarine.app/releases/cli/latest.txt)
TARGET=aarch64-apple-darwin   # or x86_64-unknown-linux-gnu
curl -fsSLO "https://octarine.app/releases/cli/${VERSION}/octarine-cli-v${VERSION}-${TARGET}.tar.gz"
tar -xzf "octarine-cli-v${VERSION}-${TARGET}.tar.gz"
mkdir -p ~/.local/bin
install -m 755 octarine ~/.local/bin/octarine
```

On Windows, download `octarine-cli-v<version>-x86_64-pc-windows-msvc.zip`, extract `octarine.exe`, move it into a permanent directory, and add that directory to your user `PATH`.

## Install From A Source Checkout

Contributors can install the current checkout with:

```bash
pnpm run cli-install
```

This builds the Rust crate and installs `octarine` through Cargo.

## Select A Workspace

Set a default workspace once by name, UUID, or path:

```bash
octarine workspace use "Work Notes"
octarine note list
```

`workspace use` saves the default in the CLI's settings file. See [Set Defaults](#set-defaults) below.

You can also choose a workspace for one command or for the current shell:

```bash
octarine --workspace ~/Notes note list
export OCTARINE_WORKSPACE="$HOME/Notes"
```

The CLI chooses a workspace in this order:

1. `--workspace`
2. `OCTARINE_WORKSPACE`
3. The nearest parent directory containing `.octarine`
4. The default saved with `octarine workspace use` or `octarine config set workspace`
5. The only workspace registered by the desktop app

Run `octarine workspace show` to see which workspace is active. Its `resolvedFrom` field reports which rule chose it. Use `octarine workspace list` to see every registered workspace.

## Set Defaults

`octarine config` manages user-level CLI settings, the way `git config` manages Git settings.

```bash
octarine config list                    # show settings and descriptions
octarine config set format json         # default output format
octarine config get format
octarine config unset format
octarine config path                    # location of cli.toml
```

| Key | Purpose |
| --- | --- |
| `workspace` | Default workspace name, UUID, or path. |
| `format` | Default output format: `table`, `plain`, `json`, or `jsonl`. |

Settings are stored in `cli.toml` in your user configuration directory, such as `~/Library/Application Support/octarine/cli.toml` on macOS. Set `OCTARINE_CONFIG` to use a different file.

## Update The CLI

Check for a newer CLI release without installing it:

```bash
octarine update --check
```

Check and interactively install an available update:

```bash
octarine update
```

For a non-interactive environment, opt in explicitly:

```bash
octarine update --yes --non-interactive
```

The updater downloads the signed release manifest, selects the archive for the current platform, verifies the manifest signature and archive SHA-256 digest, then replaces the current executable. Other CLI commands do not contact the update service.

CLI updates are independent of the desktop app's update checks. Updating one does not update the other.

#### Quick Answers

### Does installing Octarine desktop also install the CLI?

No. The CLI is a separate executable. Install it with the one-line install script, a release archive, or a source checkout.

### Can the CLI update without a desktop release?

Yes. CLI releases use independent `cli-v*` versions and can be published without rebuilding the desktop app.

### How do I stop passing --workspace on every command?

Run `octarine workspace use "<name>"` once. The CLI saves it as the default workspace.

### Does Octarine check for CLI updates during normal commands?

No. The CLI contacts the update service only when you run `octarine update`.