Metadata-Version: 2.4
Name: primethink-cli
Version: 1.3.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: mcp
Requires-Dist: mcp>=1.2.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: mcp>=1.2.0; python_version >= "3.10" and 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 mcp` | Run PrimeThink as an MCP server (exposes the API as tools over stdio) |
| `pt install-skill` | Install the bundled CLI agent skill for Claude Code and compatible agents |
| `pt install-developer-skill` | Install the complete public PrimeThink developer skill, including nested resources |
| `pt live-app new` | Scaffold a React or HTML Live App from a GitHub template catalog |
| `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
```

## Live App Scaffolding

Create a new Live App project without configuring an API profile:

```bash
# Default: React + Tailwind + Flowbite
pt live-app new ./my-live-app

# Other common variants
pt live-app new ./simple-html --framework html --no-flowbite
pt live-app new ./plain-react --no-tailwind --no-flowbite

# Use a custom catalog and pin it for reproducible generation
pt live-app new ./my-live-app \
  --repo-url https://github.com/acme/primethink-templates \
  --ref v2.0.0
```

The destination must not already exist. Flowbite requires Tailwind. The command downloads a public GitHub repository and selects a template from `live-app-templates/manifest.json`; it never runs `npm install` or any generated code. Read the generated `README.md` for preview, build, and deployment instructions.

## MCP Server

The same code that powers the `pt` CLI can run as an [MCP](https://modelcontextprotocol.io)
server, exposing every API command as a tool that MCP clients (Claude Code,
Claude Desktop, and others) can call directly — no shelling out to `pt`.

The MCP SDK is an optional dependency, so CLI-only installs stay lean:

```bash
pip install 'primethink-cli[mcp]'   # requires Python 3.10+
pt mcp                              # serve over stdio
```

Authentication reuses the same profiles and environment variables as the CLI.
Point your MCP client at `pt mcp` and provide a token via the server's env, for
example (Claude Desktop / Claude Code `mcpServers` config):

```json
{
  "mcpServers": {
    "primethink": {
      "command": "pt",
      "args": ["mcp"],
      "env": { "PRIMETHINK_TOKEN": "your-api-token" }
    }
  }
}
```

Without `PRIMETHINK_TOKEN` in the client config, the server falls back to your
configured active profile (`~/.primethink/config.json`); individual tools also
accept optional `profile` and `api_url` arguments. Every CLI command has a tool
equivalent — messaging, chats, collections, tasks, agents, semantic search, and
image generation. See the [CLI reference](docs/cli-reference.md#mcp-server-pt-mcp)
for the full tool list.

## Agent Tools Plugin

Beyond the CLI and MCP server, this repo also ships **[`primethink-agent-tools`](internal_tools/)**
(under `internal_tools/`) — a plugin that exposes the PrimeThink admin/management
API (tasks, agents, chats, collections) as **LangChain tools for PrimeThink
agents**, reusing the same client code as `pt`. It's a separate distribution that
depends on `primethink-cli`, so the CLI stays lean, and the plugin is installed
only in the agent runtime:

```bash
pip install primethink-cli primethink-agent-tools
```

The PrimeThink API discovers it automatically via the `primethink.tools` entry
point. Authentication uses a per-user `ADMIN_PRIMETHINK_API_TOKEN` setting. See
[`internal_tools/README.md`](internal_tools/README.md) for the tool list, auth,
and setup.

## Agent Skills

The CLI supports two complementary [Agent Skills](https://code.claude.com/docs/en/skills):

- **`primethink-cli`** teaches agents how to use `pt`. It ships inside the pip package and installs offline with `pt install-skill`.
- **`primethink-developer`** teaches agents to build PrimeThink Live Apps, Tasks, and SDK integrations. It is downloaded free from the public [`primethink-app-templates`](https://github.com/primethink-ai/primethink-app-templates/tree/main/skills/primethink-developer) repository with every nested library and reference file.

```bash
# Install either skill for all projects (~/.claude/skills)
pt install-skill
pt install-developer-skill

# Install the developer skill only for the current repository
pt install-developer-skill --project

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

# Pin the public source for reproducibility
pt install-developer-skill --ref main
```

Neither installer needs a PrimeThink API token. `install-developer-skill` needs internet access but no paid service or GitHub credentials; `--force` replaces the complete existing `primethink-developer/` folder only after the replacement archive has been downloaded and staged successfully.

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