primethink-cli 1.1.0

PrimeThink CLI - A powerful tool for interacting with PrimeThink AI API

PrimeThink CLI

Command Line Interface for interacting with the PrimeThink API.

Installation

pip install primethink-cli

See the Installation Guide for install scripts, Homebrew, and troubleshooting.

Quick Start

1. Configure your API token (from Settings → API Keys in the PrimeThink app):

pt profile add --token YOUR_API_TOKEN

2. Use the CLI:

pt task actions
pt task execute --action "action-name" --message "your message"
pt chat send CHAT_ID --message "your message"
pt chat send --agent AGENT_ID --message "your message"

Commands at a Glance

Command	Description
pt version	Display the CLI version
pt whoami	Show the authenticated user and their groups
pt install-skill	Install the bundled agent skill for Claude Code and compatible agents
pt profile add	Configure an API token for a profile
pt profile use	Switch the active profile
pt profile list	List configured profiles
pt profile remove	Remove a profile
pt chat send	Send a message to a chat (by ID/mention) or an agent
pt chat list	List chats (paginated, filterable by star/archive/workspace)
pt chat create	Create a new chat
pt chat rename	Rename a chat
pt chat goal	Update a chat's goal
pt chat messages	List a chat's messages (cursor-paginated)
pt chat archive / pt chat unarchive	Archive / unarchive a chat
pt chat delete	Delete a chat (asks for confirmation; --yes to skip)
pt chat list-files	List files and directories in a chat
pt chat upload-files	Upload local files to a chat
pt chat download-file	Download a file from a chat
pt chat sync-to	Sync a local directory into a chat
pt chat sync-from	Sync a chat's files to a local directory
pt chat sync	Two-way sync between a chat folder and a local directory
pt collection list	List collections (paginated, searchable)
pt collection list-files	List files and directories in a collection
pt collection upload-files	Upload local files to a collection
pt collection download-file	Download a file from a collection
pt collection sync-to	Sync a local directory into a collection
pt collection sync-from	Sync a collection's files to a local directory
pt agent list	List agents (virtual assistants), filterable by name/type/status
pt agent get	Fetch an agent's details as JSON
pt agent create	Create an agent
pt agent update	Update fields on an existing agent
pt agent delete	Delete an agent (asks for confirmation; --yes to skip)
pt agent types	List available agent types
pt task actions	List available task actions
pt task execute	Execute a task action with a message and optional files
pt task create	Create a task (supports schedules, canvases, and more)
pt task update	Update fields on an existing task
pt task get	Fetch a task's details as JSON
pt task delete	Delete a task (asks for confirmation; --yes to skip)
pt task duplicate	Duplicate a task
pt task publish / pt task unpublish	Make a task public / private
pt task export	Export a task's portable config as JSON (for pt task import)
pt task import	Create a new task from an exported JSON file (deploy across environments with --profile)
pt task create-version	Snapshot a task's current state as a named version
pt task upload-image	Upload an image for a task
pt search documents	Semantic search across documents in a vector store collection
pt search chat	Semantic search within a chat
pt search collection	Semantic search within a collection
pt search messages	Semantic search across chat messages
pt image generate	Generate an AI image and save it locally

Every command that calls the API also accepts --profile (use a specific profile for one request) and --api-url/-u (override the API URL for one request). See the full CLI reference for every option and example.

Tip: -p is the short flag for --profile in the pt task, pt agent, and pt search groups, pt image generate, and pt whoami, but in the pt chat and pt collection groups there is no -p for profile — there -p means --path (a directory inside the chat/collection) on the file commands. Use the long form --profile when in doubt.

Configuration

Token Management

The CLI supports multiple token profiles, allowing you to switch between different accounts or API endpoints.

# Configure a profile (creates it, or overwrites an existing one)
pt profile add --token YOUR_API_TOKEN --profile default

# Optionally with a custom API URL
pt profile add --token STAGING_TOKEN --profile staging --api-url https://staging-api.example.com

# List, switch, remove
pt profile list
pt profile use staging
pt profile remove old-profile

Options for pt profile add:

• --token, -t: Your API token (required)
• --profile, -p: Profile name (default: "default")
• --api-url, -u: Custom API URL (optional, default: https://api.primethink.ai)

Configuration File

The CLI stores configuration in ~/.primethink/config.json:

{
  "active_profile": "default",
  "profiles": {
    "default": {
      "token": "your-api-token"
    },
    "staging": {
      "token": "your-staging-token",
      "api_url": "https://staging-api.example.com"
    }
  }
}

Keep this file secure — it contains your API tokens (chmod 600 ~/.primethink/config.json).

Environment Variables

All environment variables are optional overrides — when unset, the CLI uses the config file and its built-in defaults:

Variable	Description	Default when unset
PRIMETHINK_TOKEN	API token, bypassing the config file (useful for CI/CD)	Token from the active profile
PRIMETHINK_API_URL	API base URL override	Profile's api_url, otherwise https://api.primethink.ai
PRIMETHINK_PROFILE	Profile to use when --profile is not passed	The active profile
PRIMETHINK_CONFIG_PATH	Custom config file path	~/.primethink/config.json
PRIMETHINK_DEBUG	Set to 1 to print request/response debug info to stderr	Disabled

Precedence, highest first: command-line flag → environment variable → config file → built-in default. See docs/install.md for details.

Usage Examples

Messaging and actions

# List available actions, optionally with a specific profile
pt task actions
pt task actions --profile production

# Execute an action with attachments
pt task execute --action summarize --message "Summarize these" --files q1.pdf --files q2.pdf

# Message a chat by ID or mention name
pt chat send 123 --message "Hello from the CLI"
pt chat send @my-assistant --message "Review this" --files report.pdf

# Fire-and-forget (don't wait for the response)
pt chat send 123 --message "Long-running job" --async

# Message an agent directly
pt chat send --agent 1 --message "Analyze this data" --files data.csv

Managing chats

# Find a chat
pt chat list --search onboarding --starred

# Create one, then adjust it
pt chat create --name "Q3 planning" --goal "Track the Q3 launch" --virtual-assistant-id 7
pt chat rename 123 "Q3 planning (final)"
pt chat goal 123 --goal-file ./new-goal.md

Chat and collection files

# Browse and fetch chat files
pt chat list-files 123
pt chat download-file 123 456 --output report.pdf

# Mirror a local folder into a chat (PDFs only, including subfolders)
pt chat sync-to 123 ./reports --pattern '*.pdf' --recursive

# Back up a whole chat workspace locally
pt chat sync-from 123 ./chat-backup

# Collections work the same way, plus discovery
pt collection list --search contracts
pt collection sync-to 42 ./knowledge-base --recursive

Semantic search

# Search a chat, a collection, documents, or messages by meaning
pt search chat 123 "what did we decide about the deadline"
pt search collection 42 "termination clause" --top-k 3
pt search documents "refund policy" --collection-name kb
pt search messages "standup notes" --collection-name msgs --user-id 2

Agents

# Discover agent types, then create an agent
pt agent types
pt agent create --name "Support bot" --public-description "Answers support questions" --type-id 1

# Find, inspect, adjust
pt agent list --search support
pt agent get 7
pt agent update 7 --description-file ./instructions.md

# Message an agent (same command as chat messaging)
pt chat send --agent 7 --message "Analyze this" --files data.csv

Tasks

# Create a scheduled task
pt task create \
  --name "Morning briefing" \
  --description "Daily news summary" \
  --type private \
  --virtual-assistant-id 7 \
  --schedule-nl "every weekday at 8am" \
  --schedule-prompt "Prepare the morning briefing"

# Inspect and update it
pt task get 99
pt task update 99 --schedule-nl "every weekday at 7am"

# Snapshot a version, add a cover image
pt task create-version 99 --version-name "v2"
pt task upload-image 99 ./cover.png

# Export the task config, check it into git, deploy it elsewhere
pt task export 99 --output tasks/briefing.json
pt task import tasks/briefing.json --profile production

# Generate an image with AI
pt image generate --prompt "A lighthouse at dawn" --output lighthouse.png

Agent Skill

This repo ships an Agent Skill at skills/primethink-cli/SKILL.md that teaches AI coding agents (Claude Code and other SKILL.md-compatible agents) how to use pt correctly — command map, common workflows, and pitfalls.

The skill ships inside the pip package, so installing it is one command:

# Available in all your projects (~/.claude/skills)
pt install-skill

# Just for the current repo (./.claude/skills — commit it to share with your team)
pt install-skill --project

# Custom skills directory / upgrade an existing install
pt install-skill --dir ~/.config/my-agent/skills
pt install-skill --force

You can also simply copy skills/primethink-cli/ into any skills directory by hand.

Documentation

• CLI Reference — every command, option, and example
• User Guide — walkthroughs, use cases, tips, troubleshooting
• Installation Guide — install methods and troubleshooting
• API Specifications — the API endpoints behind each command
• Developer Guide — contributing, architecture, testing

Development

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest -q

# Run tests with coverage
pytest -q --cov=primethink --cov-report=html

See the Developer Guide for architecture notes and the release process.

License

MIT License

Support

For issues and questions, please visit: https://primethink.ai