CLI Setup and Updates

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:

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

On Windows, run in 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.

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

Confirm the installation:

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:

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:

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:

octarine workspace use "Work Notes"
octarine note list

workspace use saves the default in the CLI's settings file. See Set Defaults below.

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

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.

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:

octarine update --check

Check and interactively install an available update:

octarine update

For a non-interactive environment, opt in explicitly:

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