Manage contacts, events, channels, companies, and analytics from the command line. Built for humans and AI agents. Structured JSON output. 10 agent skills included.

npm install -g @talkvalue/cli

Contents

• Prerequisites
• Quick Start
• Why TalkValue CLI?
• Authentication
• Commands
• AI Agent Skills
• Output Format
• Pagination
• Environment Variables
• Exit Codes
• License

Prerequisites

• Node.js 24+
• A TalkValue account with at least one organization

Quick Start

talkvalue auth login
talkvalue path person list
talkvalue path event person list 16 --sort joinedAt:desc --json

Why TalkValue CLI?

For humans — stop clicking through the UI to export contacts or check event registrants. Get --help on every command, pipe output to jq, and script your workflows.

For AI agents — every response is structured JSON. Pair it with the included agent skills and your LLM can manage contacts, events, and imports without custom tooling.

# List people in a channel, sorted by join date
talkvalue path channel people 5 --sort joinedAt:desc --json

# Export event registrants to CSV
talkvalue path event person export 16 > registrants.csv

# Analyze a CSV before importing
talkvalue path import analyze --file contacts.csv --json

# Channel attribution across events
talkvalue path analysis channel attribution 3 --event-id 16 --event-id 22 --json

Authentication

The CLI supports multiple auth workflows so it works on your laptop and in CI.

Interactive (local desktop)

talkvalue auth login     # browser-based OAuth device flow; select organization

CI / scripting

export TALKVALUE_TOKEN=<bearer-token>
talkvalue path person list    # just works

Multi-profile support

Each profile stores org_id, org_name, member_email, and auth method. Use auth switch to change the active org, or --profile <name> to target a specific one.

| Command | Description | |---------|-------------| | auth login | Authenticate via OAuth device flow; select organization | | auth status | Show current profile, email, org | | auth switch [org] | Switch active organization | | auth list | List all saved profiles | | auth logout | Remove profile and credentials |

Precedence

| Priority | Source | Set via | |----------|--------|---------| | 1 | Bearer token | TALKVALUE_TOKEN | | 2 | OAuth profile | talkvalue auth login |

Commands

All data commands live under the path prefix. Run talkvalue [command] --help for full usage.

| Command | Description | |---------|-------------| | path overview | Dashboard summary and stats | | path person | List, get, update, delete, merge, export contacts | | path event | Manage events and event participants | | path channel | Manage channels and channel members | | path company | List, get, update companies and company members | | path analysis | Channel attribution, audience overlap, event trends | | path import | Analyze CSV, create import jobs, export failures | | version | Show CLI version |

Global Flags

| Flag | Description | |------|-------------| | --format <json\|table\|csv> | Output format (default: table for TTY, json for pipe) | | --json | Shorthand for --format json | | --profile <name> | Use a specific auth profile | | --api-url <url> | API base URL override | | --no-color | Disable colored output |

AI Agent Skills

The repo ships 10 agent skills (SKILL.md files) — one for every command group, plus recipes for common workflows. Pair them with any AI coding assistant for structured CLI access to TalkValue.

# Install all skills at once
npx skills add https://github.com/talkvalue/cli

# Or pick only what you need
npx skills add https://github.com/talkvalue/cli/tree/main/skills/talkvalue-person
npx skills add https://github.com/talkvalue/cli/tree/main/skills/talkvalue-event

Skills Index

| Skill | Description | |-------|-------------| | talkvalue-shared | Auth, global flags, output format, environment variables | | talkvalue-person | Manage contacts: list, get, update, delete, merge, export, activity | | talkvalue-event | Manage events and event participants | | talkvalue-channel | Manage channels and channel members | | talkvalue-company | View and manage companies | | talkvalue-analysis | Channel attribution, audience overlap, event insights | | talkvalue-import | CSV import: analyze, create jobs, monitor, export failures |

Recipes

| Recipe | Description | |--------|-------------| | recipe-new-registrants | Find this month's event registrants | | recipe-csv-import | Full import workflow: analyze → create → monitor → export failures | | recipe-channel-analysis | Channel attribution + audience overlap analysis |

Output Format

All output — success and errors — is structured JSON when piped. Format is auto-detected:

• TTY (terminal) → table
• Pipe/redirect → json
• Override with --format <format> or --json

{ "data": { ... } }                    // single resource
{ "data": [...], "pagination": {...} } // paginated list

Errors are written to stderr:

{ "error": { "message": "..." } }

Export commands (person export, channel export, etc.) always produce CSV regardless of --format.

Pagination

| Flag | Description | |------|-------------| | --page <n> | Page number (1-indexed) | | --page-size <n> | Results per page | | --sort <field:dir> | Sort expression; repeatable (e.g. joinedAt:desc) |

--page and --page-size are available on all list subcommands. --sort is available on person, event person, channel people, and company person lists.

talkvalue path person list --page 2 --page-size 50 --sort joinedAt:desc

Environment Variables

| Variable | Description | |----------|-------------| | TALKVALUE_TOKEN | Bearer token — skips interactive auth (highest priority) | | TALKVALUE_API_URL | API base URL override | | TALKVALUE_AUTH_API_URL | Auth API base URL override | | TALKVALUE_PROFILE | Active profile override | | NO_COLOR | Disable colored output | | FORCE_COLOR | Force colored output |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Usage error (bad arguments) | | 3 | Authentication error | | 4 | Not found | | 5 | Forbidden |

talkvalue path person get 999999
echo $?   # 4 — not found

License

ISC