operately/cli at main · operately/operately · GitHub
Skip to content

cli

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

cli

Folders and files

README.md

Operately CLI

Official command-line interface for the Operately external API.

npm version License

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 243 endpoint commands across 11 namespaces:

  • comments
  • companies
  • documents
  • goals
  • notifications
  • people
  • project_templates
  • projects
  • reactions
  • 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|signup|join|create-company|profiles|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

Repeated flags are the canonical form. For compatibility with scripts and agents, list flags also accept a JSON array string:

operately notifications mark_many_as_read --ids '["n1","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_document \
  --space-id s1 \
  --name "Guide" \
  --content "# Getting Started\n\nWelcome to the team."

Prefer --<field>-file for multiline markdown content:

operately documents create_document \
  --space-id s1 \
  --name "Guide" \
  --content-file ./guide.md

The same markdown fields also accept a file path via --<field>-file:

operately projects update_description \
  --project-id p1 \
  --description-file ./roadmap.md

Markdown files can contain GitHub-style pipe tables:

| Milestone | Status |
| --- | --- |
| **Launch** | Ready |
| Review | First pass<br>Final pass |

Use the same --content-file or --description-file flags. Tables support inline formatting, links, escaped pipes (\|), and <br> cell breaks. Short rows are padded; excess cells cause an input error. Alignment markers are accepted but not stored. Exporting a headerless web table adds an empty header row, which remains when imported. Mentions retain their @label text; Markdown does not carry person IDs. Images in cells become links with their labels.

Table input requires CLI 1.10.0 or later.

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-ids person1 \
  --assignee-ids person2 \
  --due-date 2026-06-30

Output Options

For API endpoint commands:

# Pretty JSON (default)
operately people get_me

# Pretty JSON (explicit alias)
operately people get_me --json

# 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-ids person1 \
  --assignee-ids person2 \
  --due-date 2026-06-30

# Docs & Files
operately documents list_contents --space-id s1
operately documents create_document --space-id s1 --name "Guide" --content "# Guide"
operately documents create_link --space-id s1 --name "Handbook" --url "https://example.com" --type other
operately documents create_file --space-id s1 --file ./report.pdf

Docs & Files commands scope a hub with exactly one of --space-id, --project-id, or --goal-id. For folder listing, --folder-id alone is enough.

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