Operately CLI

Official command-line interface for the Operately external API.

Installation

npm install -g @operately/operately-cli

The package installs two equivalent binaries:

• operately
• op

Verify the installed version:

operately --version
# or
operately version

Updating

npm update -g @operately/operately-cli

Or:

npm install -g @operately/operately-cli@latest

Quick Start

# Save a token to the default profile
operately auth login --token <your-token>

# Verify authentication
operately auth whoami

# Explore the CLI
operately --help
operately projects --help
operately projects create --help

# Run API commands
operately people get_me
operately spaces list
operately companies get_work_map

Current CLI Shape

The current bundled API catalog exposes 196 endpoint commands across 12 namespaces:

• comments
• companies
• documents
• goals
• links
• notifications
• people
• projects
• reactions
• resource_hubs
• spaces
• tasks

All API endpoint commands in the current catalog are namespaced. There are no root API commands such as operately get_me.

Command Structure

API endpoint commands use this shape:

operately <namespace> <command> [flags]

Examples:

operately people get_me
operately projects list --include-space
operately projects get --id p1 --include-space
operately tasks list --project-id p1

Utility commands are separate from API endpoints:

operately auth <login|status|whoami|logout> [flags]
operately --version
operately help [namespace] [command]

Help And Discovery

# General help
operately --help
operately help

# Namespace help
operately projects --help
operately help projects

# Command help
operately projects create --help
operately help projects create

# Auth help
operately auth --help
operately help auth login

Authentication

The CLI resolves credentials in this order:

1. Per-command flags
2. Environment variables
3. Saved profile values

Save A Profile

operately auth login --token <token>
operately auth status
operately auth whoami

Profiles are stored in ~/.operately/config.json.

Use --base-url when talking to a non-default environment:

# Production
operately auth login --token op_live_xxx

# Staging
operately auth login --token op_staging_xxx --profile staging --base-url https://staging.operately.com

# Local development
operately auth login --token op_local_xxx --profile local --base-url http://localhost:4000

If no base URL is configured, the CLI defaults to:

https://app.operately.com

Environment Variables

export OPERATELY_API_TOKEN=op_live_xxx
export OPERATELY_BASE_URL=https://app.operately.com
export OPERATELY_PROFILE=default

operately people get_me

Per-Command Overrides

operately people get_me --token <token>
operately people get_me --profile staging
operately people get_me --base-url https://staging.operately.com

Flags And Input Encoding

Flags map from API field names to kebab-case:

# project_id -> --project-id
operately projects update_name --project-id p1 --name "New Name"

Booleans:

operately projects get --id p1 --include-space
operately projects get --id p1 --include-space=true

Nulls:

operately goals update_due_date --goal-id g1 --due-date null

Arrays:

operately notifications mark_many_as_read --ids n1 --ids n2

Nested objects and lists use dot-index notation:

operately projects update_task_statuses \
  --project-id p1 \
  --task-statuses.0.id todo \
  --task-statuses.0.label "To Do" \
  --task-statuses.0.color gray \
  --task-statuses.0.index 0 \
  --task-statuses.0.value todo \
  --task-statuses.0.closed false \
  --task-statuses.1.id done \
  --task-statuses.1.label "Done" \
  --task-statuses.1.color green \
  --task-statuses.1.index 1 \
  --task-statuses.1.value done \
  --task-statuses.1.closed true

Many fields shown as <markdown> in --help accept markdown text directly:

operately documents create \
  --resource-hub-id rh1 \
  --name "Guide" \
  --content "# Getting Started\n\nWelcome to the team."

Contextual dates let you pass either an exact day or a broader period. For year, quarter, and month values, the CLI resolves the value to a real date:

• no suffix: use the end of the period
• ^: use the start of the period
• null: clear the date

Examples:

• 2026-06-30 -> exact day
• 2026 -> December 31, 2026
• 2026^ -> January 1, 2026
• 2026/q2 -> June 30, 2026
• 2026/q2^ -> April 1, 2026
• 2026/06 -> June 30, 2026
• 2026/06^ -> June 1, 2026

Example command:

operately tasks create \
  --type project \
  --id p1 \
  --name "Design mockups" \
  --assignee-id null \
  --due-date 2026-06-30

Output Options

For API endpoint commands:

# Pretty JSON (default)
operately people get_me

# Compact JSON
operately people get_me --compact

# Write JSON to a file
operately projects get --id p1 --output ./project.json

# Print request details while executing
operately people get_me --verbose

Common Commands

# People
operately people get_me

# Companies
operately companies get_work_map

# Spaces
operately spaces list --include-members
operately spaces create --name "Engineering" --mission "Build great products" --company-permissions 10 --public-permissions 0

# Projects
operately projects list --include-space --include-milestones
operately projects get --id p1 --include-space
operately projects create \
  --space-id s1 \
  --name "Q2 Product Roadmap" \
  --anonymous-access-level 0 \
  --company-access-level 10 \
  --space-access-level 70

# Goals
operately goals list
operately goals create \
  --space-id s1 \
  --name "Revenue Goal" \
  --anonymous-access-level 0 \
  --company-access-level 10 \
  --space-access-level 70

# Tasks
operately tasks list --project-id p1
operately tasks create \
  --type project \
  --id p1 \
  --name "Design mockups" \
  --assignee-id null \
  --due-date 2026-06-30

# Resource hubs and documents
operately resource_hubs list_nodes --resource-hub-id rh1
operately documents create --resource-hub-id rh1 --name "Guide" --content "# Guide"

Many create and update commands have additional required fields. Use --help on the specific command before scripting it.

Exit Codes

• 0 - Success
• 1 - auth logout had nothing to clear for the selected profile
• 2 - CLI usage, validation, or help error
• 3 - Missing authentication token/config
• 4 - API 4xx error, including authentication failures
• 5 - API 5xx, network, or fatal error

Command Catalog

For the full generated command list, see docs/commands.md.

API Token

Generate an API token in Operately, then use it with:

operately auth login --token <your-token>

License

Apache-2.0

Support

• GitHub Issues