TalkValue CLI

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