0.2.0 • Published 22h agoCLI

@commonroomio/cli

Licence

Apache-2.0

Version

0.2.0

Deps

Size

2.0 MB

Vulns

Weekly

Summary Dependency Versions

Common Room CLI (`cr`)

Common Room from the command line — a headless, scriptable surface for automation pipelines, scheduled jobs, and AI agents. JSON-first output, --dry-run on every mutation, and machine-readable command discovery via cr agent-context.

Install

npm install -g @commonroomio/cli

Requires Node.js >=22.0.0.

Quick start

cr auth login                       # Sign in (opens browser)
cr catalog list                     # Browse object types
cr object list Contact --limit 5    # Fetch records

Run any command with --help for full flag docs, or cr agent-context --json for a machine-readable description of the entire CLI surface.

Authentication

Mode	When	How
Browser OAuth (PKCE)	Interactive terminal	`cr auth login` — opens browser, callback on `localhost:9876`
Device flow	Headless / SSH	`cr auth login --device` — prints a verification URL + code, polls for the grant
Static token	CI/CD, scripts	`export COMMONROOM_API_TOKEN=…` — skips `cr auth login` entirely

Tokens are stored at ~/.commonroom/config.json (mode 0600) and refreshed automatically before expiry. Sign out with cr auth logout, verify state with cr auth status, and switch communities with cr config set communityId <id>.

Commands

A few headline commands:

cr catalog list                                  # List object types
cr catalog describe Contact                      # Inspect fields on a type
cr object list Contact --limit 5                 # List records
cr object get c_abc123                           # Fetch by ID (type inferred)
cr object create Contact --file payload.json     # Create from a JSON payload
cr contact create --email a@example.com --full-name "Alice"

The CLI also covers contact, organization, activity, segment, tag, and note resources with list / create / update shortcuts. Every create and update accepts --dry-run to preview the payload without sending the request.

Segments and organizations can be renamed in place, and tags are created and assigned without leaving the CLI:

cr segment update s_42 --name "Renamed segment"      # ID and memberships preserved
cr organization update o_88 --name "Acme, Inc."
cr tag create --name Champion --entity-type contact  # → { "id": "l_7", ... }
cr object list Tag                                   # look up existing tag IDs
cr contact update c_1 --tag-add l_7 --tag-remove l_9 # unlisted tags untouched

For the complete command surface — every command, flag, and supported object type — run cr agent-context --json.

Output

The CLI emits JSON when stdout isn't a TTY (or when --json is passed) and a shell-friendly text format otherwise. List commands wrap records in an envelope so pagination survives pipes:

{
  "records": [/* ... */],
  "nextCursor": "abc123",
  "truncated": true,
  "hint": "Pass --cursor=abc123 to fetch the next page, or narrow with --filter / --limit."
}

In text mode the cursor is printed to stderr as [next page: --cursor=…] so stdout stays clean for pipes.

Filters

--filter accepts inline JSON; --filter-file reads from a file. Run cr catalog describe <type> for the filterable fields on an object type, or cr agent-context --json for the full filter schema:

{
  "type": "and",
  "clauses": [
    { "type": "stringFilter", "field": "fullName", "params": { "op": "like", "value": "Tracy" } }
  ]
}

cr contact list --email / --full-name and cr organization list --domain / --name build simple filters for the common case so you don't have to write JSON by hand.