Installation

The Octo CLI installs as a global npm package named @appbox.ai/oneocto-cli and exposes a single command, oneocto.

Requirements

Requirement	Detail
Node.js	Version 22 or newer.
npm	Installed alongside Node.js.
Network access	The CLI calls the Octo API and the identity provider over HTTPS.

Install

npm install -g @appbox.ai/oneocto-cli

Verify the install

oneocto --version

The command prints the running version. If the shell reports that oneocto is not found, the npm global bin directory is not on your PATH. Run npm prefix -g to find the global prefix and add its bin directory to your shell profile.

Upgrade

npm install -g @appbox.ai/oneocto-cli@latest

The CLI follows semantic versioning: a patch release fixes behavior, a minor release adds backward-compatible commands, and a major release changes an existing command or contract. Check oneocto --version after upgrading.

Uninstall

npm uninstall -g @appbox.ai/oneocto-cli

Uninstalling removes the command but leaves saved tenant configuration in place. Run oneocto auth logout first if you also want the stored credentials removed.

Configuration

The CLI reads configuration in this order: an explicit command flag, then an environment variable, then the saved tenant. Environment variables are the right choice for CI jobs and agent runtimes where there is no interactive login.

Variable	Purpose
`ONEOCTO_API_URL`	API base URL, overriding the saved tenant.
`ONEOCTO_TENANT_ID`	Tenant slug.
`ONEOCTO_SPACE_ID`	Space id used when a command does not pass `--space-id`.
`ONEOCTO_ACCESS_TOKEN`	Pre-issued access token, skipping the saved login.
`ONEOCTO_CONFIG_DIR`	Directory where tenant configuration is stored.

Tenant metadata is written to the config directory. Credentials are kept in the OS keychain and are never written to the config file.

FAQ

Can I install the CLI per project instead of globally? Yes. Install it as a dev dependency and invoke it through your package runner. A global install is simpler when several projects use the same tenant.

Does the CLI work without an interactive terminal? Yes. Set ONEOCTO_ACCESS_TOKEN along with ONEOCTO_API_URL and ONEOCTO_SPACE_ID, and no saved login is needed. Interactive extras such as the tenant picker are skipped automatically.

Where does the CLI store my password? It does not. Sign-in exchanges your credentials for tokens, and those tokens live in the OS keychain.

CLI - what the CLI is and how it is organized
Authentication - sign in and select a tenant and space
Command Reference - global options and command groups