Metadata-Version: 2.4
Name: primethink-cli
Version: 1.1.0
Summary: PrimeThink CLI - A powerful tool for interacting with PrimeThink AI API
Author-email: PrimeThink <support@primethink.ai>
License-Expression: MIT
Project-URL: Homepage, https://primethink.ai
Project-URL: Documentation, https://primethink.ai/cli/install
Project-URL: Repository, https://github.com/primethink-ai/primethink-cli
Project-URL: Issues, https://github.com/primethink-ai/primethink-cli/issues
Keywords: cli,ai,primethink,api,assistant
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# PrimeThink CLI

Command Line Interface for interacting with the PrimeThink API.

## Installation

```bash
pip install primethink-cli
```

See the [Installation Guide](docs/install.md) for install scripts, Homebrew, and troubleshooting.

## Quick Start

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

```bash
pt profile add --token YOUR_API_TOKEN
```

2. Use the CLI:

```bash
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](docs/cli-reference.md) 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.

```bash
# 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`:

```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](docs/install.md) for details.

## Usage Examples

### Messaging and actions

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](https://code.claude.com/docs/en/skills) at [`skills/primethink-cli/SKILL.md`](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:

```bash
# 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/`](skills/primethink-cli/) into any skills directory by hand.

## Documentation

- [CLI Reference](docs/cli-reference.md) — every command, option, and example
- [User Guide](USER_GUIDE.md) — walkthroughs, use cases, tips, troubleshooting
- [Installation Guide](docs/install.md) — install methods and troubleshooting
- [API Specifications](SPECS.md) — the API endpoints behind each command
- [Developer Guide](DEVELOPER.md) — contributing, architecture, testing

## Development

```bash
# 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](DEVELOPER.md) for architecture notes and the release process.

## License

MIT License

## Support

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