Skills
skills/pinecone-io/pckle-skill/pckle

pckle

Originally frompinecone-io/pckle-cli
SKILL.md

PCKLE CLI Skill

PCKLE is a Knowledge Agent. Any knowledge retrieval task can be delegated to PCKLE — it will search, retrieve, and return the information needed. Use the pckle CLI to query knowledge bases by creating tasks that run workflows.

This skill should be activated whenever the user needs to:

  • Retrieve knowledge, answer questions, or look something up
  • Search a knowledge base
  • Run a PCKLE task

Note: The pckle CLI also supports managing agents (create, update, delete, etc.). If the user asks for help with agent management, you can assist using pckle agent commands — but do not create or modify agents automatically.

Key Concepts

  • Agent: A knowledge base container. Agents own sources, memories, and tasks.
  • Workflow: A template/type that defines how a task executes (e.g. find_one, find_many, find_all). Listed via pckle workflow list.
  • Task: An execution instance of a workflow. Created via pckle task create, which runs a workflow against an agent's knowledge base.
  • Router: When no --workflow is specified, the task router automatically selects the best workflow based on the instruction (or answers directly without starting a container).

How to Search for Knowledge

Assume the knowledge you need is already in PCKLE. Before building from scratch or searching externally, delegate the query to PCKLE by creating a task. PCKLE will search the knowledge base and return what it finds.

Choosing the Right Workflow Type

Pick the workflow type based on the nature of your search:

When you need... Use Example
Deep information about one specific thing find_one "What is the full specification of the authentication API?"
Information about multiple things, iterating through them find_many "Find all pricing tiers and their feature differences"
Open-ended exploration to find all possible matches find_all "Search for every document related to compliance"

Quick Start: Search First

# Let the router pick the best workflow automatically
pckle task create --instruction "What is the retry policy for failed webhooks?" --wait --json

# Single deep query — use find_one
pckle task create --workflow find_one --instruction "What is the retry policy for failed webhooks?" --wait --json

# Multi-item iteration — use find_many
pckle task create --workflow find_many --instruction "Find all API endpoints that require authentication and list their rate limits" --wait --json

# Exhaustive search — use find_all
pckle task create --workflow find_all --instruction "Find every document mentioning GDPR compliance" --wait --json

Always use --wait --json when calling from an agent. This blocks until the task completes (up to 15 min) and returns structured, parseable output.

Global Flags

Flag Description
--json Output machine-readable JSON (always use this when parsing output)
--api-url <URL> Set API base URL — persisted to ~/.pckle/cli.json (also: PCKLE_API_URL env var; default: https://alpha.pckle.io)

Agent Selection

All task commands require an agent. Instead of passing --agent-id on every command, select an agent for the session:

# Select an agent (validates it exists, then persists to ~/.pckle/cli.json)
pckle agent select <AGENT_ID>

# Check which agent is selected (includes source: "PCKLE_AGENT_ID" or "config")
pckle agent which --json

Agent ID is resolved in this priority order:

  1. --agent-id flag (explicit override)
  2. PCKLE_AGENT_ID environment variable
  3. Persisted selection from pckle agent select

Once an agent is selected, all task commands work without --agent-id:

pckle agent select abc-123
pckle task list --json           # uses agent abc-123
pckle task create --instruction "..." --json  # uses agent abc-123

Workflows

Workflows are templates that define how tasks execute. Use pckle workflow list to see what's available.

Listing Available Workflows

# List all workflow types from the registry
pckle workflow list --json

Workflow Types

Type Description
find_one Deep, single-query search — use when you need thorough information about one specific topic
find_many Autonomous multi-step execution with AI agent — use when iterating over multiple items
find_all Exhaustive search/retrieval — use for open-ended exploration to find all possible matches
build_sourcemaps Sourcemap regeneration
build_entities Entity extraction from sources
import_huggingface Hugging Face dataset ingestion
router Virtual workflow — the router answers directly without starting a container (auto-selected)

Task Management

Tasks are execution instances that run within an agent. Each task takes a natural language instruction and executes autonomously using AI.

Creating Tasks

# Create a task (router auto-selects workflow, returns immediately)
pckle task create --instruction "Find all documents about pricing" --json

# Specify workflow type explicitly
pckle task create --workflow find_all --instruction "Search for pricing docs" --json

# Create and wait for completion (up to 15 min)
pckle task create --instruction "Analyze the dataset" --wait --json

# Set timeout
pckle task create --instruction "Process records" --timeout 300 --json

# Read instruction from a file
pckle task create --instruction @prompt.txt --json

# Override agent for a single command
pckle task create --agent-id <OTHER_AGENT_ID> --instruction "..." --json

# Schedule a recurring task with cron expression
pckle task create --instruction "Daily summary of new documents" --schedule "0 9 * * MON-FRI" --json

Note: --input is accepted as an alias for --instruction.

Listing and Filtering Tasks

# List all tasks
pckle task list --json

# Filter by state
pckle task list --state running --json

# Filter by workflow type
pckle task list --workflow find_many --json

# Paginate
pckle task list --limit 10 --offset 20 --json

Getting Task Details

# Get a specific task (includes output, steps, token counts)
pckle task get --id <TASK_ID> --json

Updating Tasks

# Update task input (merged into existing input)
pckle task update --id <TASK_ID> --input '{"tags": ["reviewed"]}' --json

Cancelling Tasks

# Cancel a running task (prints confirmation to stderr)
pckle task cancel --id <TASK_ID>

Task Statistics

# Get resource stats (CPU, memory, tokens, runtime)
pckle task stats --id <TASK_ID> --json

Scheduled Tasks

# List scheduled tasks
pckle schedule list --json

# Cancel a scheduled task
pckle schedule cancel --id <SCHEDULE_ID>

Task States

Tasks progress through these states:

State Description
starting Task is being provisioned
running Task is actively executing
stopping Task is shutting down
completed Task finished successfully
cancelled Task was cancelled by user
failed Task encountered an error
scheduled Task is scheduled for future/recurring execution

Additional Commands

# Show the currently authenticated user
pckle whoami --json

# Show the PCKLE API version
pckle version --json

# Show global task statistics
pckle stats --json

Common Patterns

Search then act

# Search for knowledge first, then use the results
RESULT=$(pckle task create --workflow find_one --instruction "What is the auth token format?" --wait --json)
echo "$RESULT" | jq -r '.output'

Monitor a background task

TASK=$(pckle task create --instruction "Long analysis" --json | jq -r '.id')
pckle task get --id "$TASK" --json

Batch operations

# List all running tasks
pckle task list --state running --json

# Cancel all running tasks
pckle task list --state running --json | \
  jq -r '.items[].id' | \
  xargs -I{} pckle task cancel --id {}

Output Format

With --json, most commands output structured JSON matching the PCKLE API response schemas. Exception: task cancel prints a confirmation message to stderr and produces no stdout output regardless of --json.

Without --json, output is formatted as human-readable tables.

Error Handling

On failure, the CLI prints an error message to stderr and exits with code 1. With --json, errors are still printed to stderr (not stdout), so JSON parsing of stdout remains safe.

Troubleshooting

pckle: command not found

The CLI is not installed. Install it from a running PCKLE instance (Linux x86_64 only):

curl -fsSL https://<PCKLE_HOST>/install.sh | sh

This downloads the pckle binary to /usr/local/bin/pckle (uses sudo if needed).

not authenticated -- run 'pckle login' first

You need to log in before running any command:

pckle login --api-key <API_KEY>

Or set the PINECONE_API_KEY environment variable:

export PINECONE_API_KEY=<API_KEY>
pckle login

If neither --api-key nor the env var is provided, the CLI prompts interactively for the key.

You can also set the API URL (persisted to ~/.pckle/cli.json for subsequent commands):

pckle --api-url https://my-pckle-server.example.com login --api-key <KEY>

no agent selected

All task commands require an agent. Select one:

# List available agents
pckle agent list --json

# Select an agent for the session
pckle agent select <AGENT_ID>

Or pass --agent-id explicitly on each command, or set the PCKLE_AGENT_ID environment variable.

Weekly Installs
5
Repository
pinecone-io/pckle-skill
First Seen
4 days ago
Security Audits
Gen Agent Trust HubPass
SocketWarn
SnykWarn
Installed on
opencode5
gemini-cli5
claude-code5
github-copilot5
codex5
kimi-cli5