CLI Overview

You don’t need to memorize any of this. If you use an AI agent like Claude Code, Cursor, or Copilot — just tell it what you need in plain language. Your agent can read this documentation and execute every command listed here on your behalf. You focus on decisions, your agent handles the syntax.

Installation

npm install -g @mossdesk/cli

pnpm add -g @mossdesk/cli

Verify it works:

moss --version

Quick Start

Get up and running in five commands:

# 1. Log in via browser
moss login

# 2. Create a contact
moss contact create --first-name "Jane" --last-name "Smith" --email "jane@acme.com"

# 3. Create a deal
moss deal create --name "Acme Enterprise" --value 50000 --stage lead

# 4. Log an interaction
moss interaction log --contact-id cnt_abc123 --type meeting --notes "Discussed Q2 roadmap"

# 5. Check your pipeline
moss pipeline show

Global Options

These options apply to every command:

Flag	Description
`--json`	Output as JSON instead of a table
`--workspace <id>`	Override the active workspace ID
`--api-key <key>`	Override the API key
`--session-token <token>`	Override the session token
`--api-url <url>`	Override the API base URL
`--request-id <id>`	Attach a request ID for tracing
`--idempotency-key <key>`	Idempotency key to prevent duplicate mutations

Output Modes

Table (default)

Human-readable table output. Column widths are fixed for consistent formatting.

moss contact list

ID       Name          Email              Company
──────── ───────────── ────────────────── ────────
cnt_a1   Jane Smith    jane@acme.com      Acme Corp
cnt_b2   Bob Chen      bob@startup.io     StartupIO

JSON

Machine-readable JSON output. Use --json with any command.

moss contact list --json

{
  "data": [
    { "id": "cnt_a1", "first_name": "Jane", "last_name": "Smith", "email": "jane@acme.com" }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

Use --json when piping output to other tools like jq, or when your AI agent needs structured data to work with.

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Validation error (invalid input)
`3`	Authentication error (missing or invalid credentials)
`4`	Not found
`5`	Rate limited

Use exit codes for scripting and automation:

moss contact show --id cnt_abc123 --json
if [ $? -eq 4 ]; then
  echo "Contact not found"
fi

Configuration

The CLI stores configuration at ~/.moss/config.json:

{
  "active_workspace": "ws_abc123",
  "workspaces": {
    "ws_abc123": {
      "api_key": "moss_k_...",
      "api_url": "https://api.mossdesk.com"
    }
  }
}

Credentials are saved via moss login (browser) or moss auth login (API key) and can be overridden per-command with --api-key and --workspace.

Command Groups

Group	Description
`auth`	Login, logout, and identity
`workspace`	Manage workspaces and invites
`key`	Manage API keys
`contact`	Manage contacts
`company`	Manage companies
`deal`	Manage deals and deal-contact links
`interaction`	Log and view interactions
`followup`	Manage follow-ups
`commitment`	Manage commitments
`tag`	Manage tags
`custom-field`	Manage custom field definitions
`pipeline`	View pipeline summary
`search`	Full-text search
`activity`	View activity timelines
`webhook`	Manage webhooks
`import` / `export`	Bulk data import and export
`notification`	Notification preferences
`audit`	View audit logs
`queue`	Dead letter queue management

Overview

Authentication

CRM Data

Views & Search

Operations

Installation

Quick Start

Global Options

Output Modes

Table (default)

JSON

Exit Codes

Configuration

Command Groups

​Installation

​Quick Start

​Global Options

​Output Modes

​Table (default)

​JSON

​Exit Codes

​Configuration

​Command Groups

Installation

Quick Start

Global Options

Output Modes

Table (default)

JSON

Exit Codes

Configuration

Command Groups