octo-cli

library0.8.0jsnpmunverified

Octo CLI (v0.8.0) is a Node.js CLI tool (requires Node >=22) for interacting with Octopus Observability platform — querying logs, alerts, traces, metrics, RUM data, LLM spans, and service topology. It provides a context+skill+tool framework designed for AI agents: agents automatically load project context (.claude/rules), use skills for troubleshooting workflows, and execute CLI commands. Releases are active on npm. Key differentiator: agents auto-generate and refresh context from code analysis and live topology data, and can parse Octopus URLs directly as query inputs. Ships TypeScript types.

devops

npm install octo-cli

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OCTO-CLI

octo-cli

devopsjavascriptv0.8.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import octo from 'octo-cli'

✗ const octo = require('octo-cli')

ESM-only since v0.8.0; CommonJS require will fail

OctoClient

✓ import { OctoClient } from 'octo-cli'

Use for programmatic access; not available via CLI

type OctoConfig

✓ import type { OctoConfig } from 'octo-cli'

✗ import { OctoConfig } from 'octo-cli'

TypeScript type export; not a runtime value

Demonstrates login, project initialization, and common observability queries (logs, traces, metrics, alerts) using octo-cli via npx.

import { execSync } from 'child_process'; // Login with token const token = process.env.OCTOPUS_TOKEN ?? ''; if (!token) { console.error('Set OCTOPUS_TOKEN env var'); process.exit(1); } // Run CLI npx style (or install globally) execSync(`npx octo-cli login --token ${token}`, { stdio: 'inherit' }); // Initialize context in project execSync('npx octo-cli init', { stdio: 'inherit' }); // Query logs execSync(`npx octo-cli logs search -e production -q "error" -l 1h -o json`, { stdio: 'inherit' }); // Query traces execSync(`npx octo-cli trace search -e production -t "service:myservice" -l 1h -o json`, { stdio: 'inherit' }); // Query metrics execSync(`npx octo-cli metrics query -e production -m "cpu.usage" -l 1h -o json`, { stdio: 'inherit' }); // List alerts execSync(`npx octo-cli alerts list -e production -s "firing" -o json`, { stdio: 'inherit' });

Debug

Known issues

breakingv0.8.0 dropped CommonJS support; require('octo-cli') throws ERR_REQUIRE_ESM

fix

Use ESM imports (import octo from 'octo-cli') or dynamic import (const octo = await import('octo-cli')).

affects: >=0.8.0

breakingNode.js >=22.0.0 required; older versions fail with engine check

fix

Upgrade Node to v22+ or use nvm/n to manage versions.

affects: >=0.8.0 <0.9.0

gotchaThe --token flag in login command expects a personal access token, not an API key; using an API key will authenticate but may lack permissions.

fix

Generate a PAT from Octopus UI under User Settings > Tokens.

affects: >=0.1.0

gotchaWhen using octo-cli via npx, the login token is stored in .octo/config; if the project root is not the current working directory, use --cwd flag.

fix

Run npx octo-cli from project root or pass --cwd <path> on all commands.

affects: >=0.5.0

deprecatedThe 'rum' subcommand was deprecated in favor of 'rum-explorer' in v0.8.0

fix

Use 'octo-cli rum-explorer list' instead of 'octo-cli rum list'.

affects: >=0.8.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/octo-cli/index.mjs from /path/to/app.js not supported.

octo-cli v0.8.0+ is ESM-only but app uses CommonJS require().

fix

Convert to ESM ("type": "module" in package.json) or use dynamic import: const octo = await import('octo-cli').

Error: The engine "node" is incompatible with this module. Expected version ">=22.0.0". Got "20.12.0"

Node.js version below minimum required 22.0.0.

fix

Upgrade Node.js to v22+ via nvm (nvm install 22) or download from nodejs.org.

Error: Invalid environment: 'prod' (valid values: 'production', 'staging', 'test', 'dev')

Environment shorthand 'prod' is not recognized; the CLI expects full environment names.

fix

Use -e production instead of -e prod.

Error: Request failed with status 403: Forbidden

Token is missing required permissions for the requested resource (e.g., querying logs in production).

fix

Verify the token has the appropriate roles (e.g., 'observability:read') in Octopus UI.

Error: Cannot find module '@modelcontextprotocol/sdk'

Optional dependency for MCP not installed; occurs when using MCP features without the SDK.

fix

Install @modelcontextprotocol/sdk: npm install @modelcontextprotocol/sdk.

Upgrade

Version history

0.8.0latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkoptionalMCP protocol support for agent integration

commanderrequiredCommand-line argument parsing

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/kanyun-inc/octo-cli ↗

packageocto-cli ↗

homepagehttps://github.com/kanyun-inc/octo-cli#readme ↗