@syngy/octopus-admin-cli

Octopus administration CLI.

Install

npm install -g @syngy/octopus-admin-cli

Login

octopus-admin-cli auth login
octopus-admin-cli auth login --no-open
octopus-admin-cli auth login --no-open --no-wait
octopus-admin-cli auth login --complete
octopus-admin-cli auth login --profile prod
octopus-admin-cli auth whoami
octopus-admin-cli auth whoami --profile prod
octopus-admin-cli auth logout

auth login prints a browser URL and an 8-digit pairing code. Open the URL, enter the code in the web page, and the CLI stores the access token and refresh token after pairing completes. Authenticated API requests use the same slauth client session path as the admin web app and refresh the access token automatically when the refresh token is still valid. The pairing code is never embedded in the URL.

Use --no-open when you only want the CLI to print the URL instead of opening the browser automatically. Use --no-wait when the browser pairing will be completed later; after pairing in the browser, run octopus-admin-cli auth login --complete. In a non-interactive shell, login automatically uses the same two-step path as --no-wait.

Profiles

Every command can run with a named local login profile:

octopus-admin-cli --profile prod config summary --json
octopus-admin-cli team list --profile staging --json

Credentials are stored per profile. If --profile is omitted, the CLI uses the current profile; when no current profile is configured, it uses default.

octopus-admin-cli auth profiles list --json
octopus-admin-cli auth profiles current --json
octopus-admin-cli auth profiles use prod
octopus-admin-cli auth profiles delete staging

Dry Run

Use global --dryrun to validate inputs and print the planned operation without executing remote requests or local writes.

octopus-admin-cli --dryrun billing team-balance transfer-points <teamId> --idempotency-key cli-001 --body-json '{"points":1}' --json
octopus-admin-cli --dryrun skill storage upload --file ./SKILL.md --prefix docs/ --json
octopus-admin-cli --dryrun auth profiles use prod

Dry run still parses JSON bodies, reads local upload files for validation, and checks generated command contracts. It does not create pairing sessions, upload files, call generated API methods, or update local profile config.

Command Groups

octopus-admin-cli config ...
octopus-admin-cli team ...
octopus-admin-cli talent ...
octopus-admin-cli skill ...
octopus-admin-cli marketplace ...
octopus-admin-cli integration ...
octopus-admin-cli billing ...
octopus-admin-cli audit ...

Use --help-json for the machine-readable command tree. The JSON tree includes per-command examples, risk labels, and generated type hints.

octopus-admin-cli --help-json

JSON Input

Commands with a request body use one JSON body source:

octopus-admin-cli talent worker create --body-json '{"name":"Ops Worker","llmModelId":"qwen3-max"}'
octopus-admin-cli marketplace plan replace-members <id> --body-file plan-members.json

For query parameters, pass a JSON object:

octopus-admin-cli talent worker list --query-json '{"limit":20}' --json

Use the example from --help-json as the single success path for each command. Do not invent flags for request fields; body fields go through --body-json or --body-file, and query fields go through --query-json.

Commands that require an idempotency key expose a dedicated option:

octopus-admin-cli billing team-balance transfer-points <teamId> --idempotency-key cli-20260616-001 --body-json '{"points":1}'

File Uploads

Upload commands are business-level composite commands. They accept local files with --file and hide raw presign, upload-url, and finalize endpoints.

octopus-admin-cli talent worker bio-picture upload <id> --file ./bio-picture.png --json
octopus-admin-cli talent worker visual-preview upload <id> --asset-type avatar --file ./avatar.png --json
octopus-admin-cli config brand-asset upload --kind login-logo --file ./logo.png --json
octopus-admin-cli skill storage upload --file ./SKILL.md --key examples/SKILL.md --json
octopus-admin-cli team files upload --team-id <teamId> --root-kind skills --file ./SKILL.md --key docs/SKILL.md --json

If --key is omitted, storage uploads use the local file name. If --prefix is provided, the default key is prefix + basename(file).

Examples

octopus-admin-cli config summary --json
octopus-admin-cli config brand get --json
octopus-admin-cli team list --query-json '{"limit":20}' --json
octopus-admin-cli team certification approve <id> --body-json '{"comment":"Approved"}'
octopus-admin-cli talent worker list --json
octopus-admin-cli talent job-tag list --json
octopus-admin-cli skill set list --json
octopus-admin-cli marketplace plan list --json
octopus-admin-cli billing balance get --json
octopus-admin-cli audit list --query-json '{"limit":50}' --json

Errors

When a command uses --json and fails, the CLI prints a structured error:

{
  "code": "AUTH_REQUIRED",
  "message": "Unauthorized. Please run: octopus-admin-cli auth login",
  "hint": "Run auth login and retry the command",
  "detail": {
    "example": "octopus-admin-cli ...",
    "typeHints": [
      {
        "source": "generated-admin-sdk",
        "operation": "v1ExampleOperation"
      }
    ]
  }
}

Exit codes:

• 2: auth required
• 3: validation error
• 4: not found
• 5: request failed