Pinecone:Cli

Pinecone CLI (pc)

Manage Pinecone from the terminal. The CLI is especially valuable for vector operations across all index types — something the MCP currently can't do.

CLI vs MCP

---

Setup

Install (macOS)

brew tap pinecone-io/tap
brew install pinecone-io/tap/pinecone

Other platforms (Linux, Windows) — download from GitHub Releases.

Authenticate

# Interactive (recommended for local dev)
pc login
pc target -o "my-org" -p "my-project"

# Service account (recommended for CI/CD)
pc auth configure --client-id "$PINECONE_CLIENT_ID" --client-secret "$PINECONE_CLIENT_SECRET"

# API key (quick testing)
pc config set-api-key $PINECONE_API_KEY

Check status: pc auth status · pc target --show

Note for agent sessions: If you need to run pc login inside an agent loop, the browser auth link may not surface correctly. It's best to authenticate before starting an agent session. Run pc login in your terminal directly, then invoke the agent once you're authenticated.

Authenticating the CLI does not set PINECONE_API_KEY

pc login authenticates the CLI tool itself — it does not set PINECONE_API_KEY in your environment. Python scripts, Node.js SDKs, and other tools that use the Pinecone SDK need PINECONE_API_KEY set separately.

Use the CLI to create a key and export it in one step:

KEY=$(pc api-key create --name agent-sdk-key --json | jq -r '.value')
export PINECONE_API_KEY="$KEY"

Without jq: run pc api-key create --name agent-sdk-key --json and copy the "value" field manually.

---

Common Commands

---

Interesting Things You Can Do

Query with custom vectors (not just text)

Unlike the MCP, the CLI lets you query any index with raw vector values — useful when you generate embeddings externally (OpenAI, HuggingFace, etc.):

pc index vector query -n my-index \
  --vector '[0.1, 0.2, ..., 0.9]' \
  --filter '{"source":{"$eq":"docs"}}' \
  -k 20 --include-metadata

Pipe embeddings directly into queries

jq -c '.embedding' doc.json | pc index vector query -n my-index --vector - -k 10

Bulk metadata update with preview

# Preview first
pc index vector update -n my-index \
  --filter '{"env":{"$eq":"staging"}}' \
  --metadata '{"env":"production"}' \
  --dry-run

# Apply
pc index vector update -n my-index \
  --filter '{"env":{"$eq":"staging"}}' \
  --metadata '{"env":"production"}'

Backup and restore

# Snapshot before a migration
pc backup create -i my-index -n "pre-migration"

# Restore to a new index if something goes wrong
pc backup restore -i <backup-uuid> -n my-index-restored

Automate in CI/CD

export PINECONE_CLIENT_ID="..."
export PINECONE_CLIENT_SECRET="..."
pc auth configure --client-id "$PINECONE_CLIENT_ID" --client-secret "$PINECONE_CLIENT_SECRET"
pc index vector upsert -n my-index --file ./vectors.jsonl --batch-size 1000

Script against JSON output

# Get all index names as a list
pc index list -j | jq -r '.[] | .name'

# Check if an index exists before creating
if ! pc index describe -n my-index -j 2>/dev/null | jq -e '.name' > /dev/null; then
  pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1
fi

---

Reference Files

• Full command reference — all commands with flags and examples
• Troubleshooting & best practices

Documentation

• CLI Quickstart
• Command Reference
• Authentication
• Target Context
• GitHub Releases

Pinecone CLI — Full Command Reference

Index Management

Create Index

# Serverless index
pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1

# With integrated embedding model
pc index create -n my-index -m cosine -c aws -r us-east-1 \
  --model multilingual-e5-large \
  --field-map text=chunk_text

# Sparse vector index
pc index create -n sparse-index -m dotproduct -c aws -r us-east-1 --vector-type sparse

# With deletion protection
pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1 --deletion-protection enabled

# From collection
pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1 --source-collection my-collection

List / Describe / Stats

pc index list                          # Summary view
pc index list --wide                   # Additional columns (host, embed, tags)
pc index list -j                       # JSON output

pc index describe -n my-index
pc index describe -n my-index -j

pc index stats -n my-index
pc index stats -n my-index --filter '{"genre":{"$eq":"rock"}}'

Configure / Delete

# Enable deletion protection
pc index configure -n my-index --deletion-protection enabled

# Add tags
pc index configure -n my-index --tags environment=production,team=ml

# Switch to dedicated read capacity
pc index configure -n my-index \
  --read-mode dedicated \
  --read-node-type b1 \
  --read-shards 2 \
  --read-replicas 2

pc index delete -n my-index

---

Vector Operations

Upsert

# From JSON file (with "vectors" array)
pc index vector upsert -n my-index --file ./vectors.json

# From JSONL file (one vector per line)
pc index vector upsert -n my-index --file ./vectors.jsonl

# Inline JSON
pc index vector upsert -n my-index --file '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3]}]}'

# From stdin
cat vectors.json | pc index vector upsert -n my-index --file -

# With namespace, custom batch size
pc index vector upsert -n my-index --namespace tenant-a --file ./vectors.json --batch-size 1000

File formats:

// JSON (vectors.json)
{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}

// JSONL (vectors.jsonl)
{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}
{"id": "vec2", "values": [0.4, 0.5, 0.6], "metadata": {"genre": "drama"}}

Query

# By vector values
pc index vector query -n my-index --vector '[0.1, 0.2, 0.3]' -k 10 --include-metadata

# By vector ID
pc index vector query -n my-index --id "doc-123" -k 10 --include-metadata

# With metadata filter
pc index vector query -n my-index \
  --vector '[0.1, 0.2, 0.3]' \
  --filter '{"genre":{"$eq":"sci-fi"}}' \
  --include-metadata

# Sparse vectors
pc index vector query -n my-index \
  --sparse-indices '[0, 5, 12]' \
  --sparse-values '[0.5, 0.3, 0.8]' \
  -k 15

# From stdin
jq -c '.embedding' doc.json | pc index vector query -n my-index --vector - -k 10

Fetch

pc index vector fetch -n my-index --ids '["vec1","vec2","vec3"]'
pc index vector fetch -n my-index --filter '{"genre":{"$eq":"rock"}}'
pc index vector fetch -n my-index --namespace tenant-a --ids '["doc-123"]'
pc index vector fetch -n my-index --filter '{"genre":{"$eq":"rock"}}' --limit 100

List / Update / Delete

# List vector IDs
pc index vector list -n my-index
pc index vector list -n my-index --namespace tenant-a --limit 50

# Update metadata or values
pc index vector update -n my-index --id "vec1" --metadata '{"category":"updated"}'
pc index vector update -n my-index --id "vec1" --values '[0.2, 0.3, 0.4]'

# Bulk update with dry-run
pc index vector update -n my-index \
  --filter '{"genre":{"$eq":"sci-fi"}}' \
  --metadata '{"genre":"fantasy"}' \
  --dry-run

# Delete by IDs or filter
pc index vector delete -n my-index --ids '["vec1","vec2"]'
pc index vector delete -n my-index --filter '{"genre":"classical"}'
pc index vector delete -n my-index --namespace old-data --all-vectors

---

Namespace Management

pc index namespace create -n my-index --name tenant-a
pc index namespace create -n my-index --name tenant-b --schema "category,brand"
pc index namespace list -n my-index
pc index namespace list -n my-index --prefix "tenant-"
pc index namespace describe -n my-index --name tenant-a
pc index namespace delete -n my-index --name tenant-a   # WARNING: deletes all vectors

---

Backup and Restore

# Create / list / describe
pc backup create -i my-index -n "nightly-backup" -d "Backup before deployment"
pc backup list
pc backup list --index-name my-index
pc backup describe -i <backup-uuid>

# Restore (creates a new index)
pc backup restore -i <backup-uuid> -n restored-index
pc backup restore -i <backup-uuid> -n restored-index --deletion-protection enabled

# Check restore job status
pc backup restore list
pc backup restore describe -i rj-abc123

# Delete backup
pc backup delete -i <backup-uuid>

---

Project Management

pc project list
pc project create -n "demo-project"
pc project create -n "demo-project" --target
pc project describe -i proj-abc123
pc project update -i proj-abc123 -n "new-name"
pc project delete -i proj-abc123

---

Organization Management

pc organization list
pc organization describe -i org-abc123
pc organization update -i org-abc123 -n "new-name"
pc organization delete -i org-abc123   # WARNING: highly destructive

---

API Key Management

pc api-key create -n "my-key"
pc api-key create -n "my-key" --store
pc api-key create -n "my-key" -i proj-abc123
pc api-key list
pc api-key describe -i key-abc123
pc api-key update -i key-abc123 --roles ProjectEditor
pc api-key delete -i key-abc123

---

Global Flags

Available on all commands:

• -h, --help — Show help
• -j, --json — JSON output (great for scripting)
• -q, --quiet — Suppress output
• --timeout — Command timeout (default: 60s, 0 to disable)

Exit Codes

• 0 — success
• 1 — error

if pc index describe -n my-index 2>/dev/null; then
  echo "Index exists"
else
  pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1
fi

Pinecone CLI — Troubleshooting & Best Practices

Troubleshooting

Authentication Issues

"Not authenticated" or "Invalid credentials"

pc auth status
pc logout
pc login
pc target -o "my-org" -p "my-project"

Service account can't access resources

pc target --show   # Verify correct project is targeted

API Key Issues

API key not working

pc config get-api-key   # Verify key is set
# API keys are scoped to org + project — get a new one if needed
pc api-key create -n "new-key" --store

Target Context Issues

"Project not found" or "Organization not found"

pc target --show
pc target --clear
pc target -o "my-org" -p "my-project"

Index Issues

Index operations failing

pc index describe -n my-index
# "Initializing" → wait and retry
# "Terminating" → recreate it

Can't delete index

# Check if deletion protection is on
pc index describe -n my-index
pc index configure -n my-index --deletion-protection disabled
pc index delete -n my-index

Vector Upload Issues

Upsert fails with dimension mismatch

pc index describe -n my-index   # Check configured dimension
# Ensure all vectors have exactly that many values

Large file upload is slow

# Use max batch size
pc index vector upsert -n my-index --file ./large.json --batch-size 1000

# Or split JSONL and loop
split -l 10000 large.jsonl chunk-
for file in chunk-*; do
  pc index vector upsert -n my-index --file "$file"
done

Query Issues

Query returns no results

pc index stats -n my-index          # Check if data exists
pc index namespace list -n my-index # Verify namespace
# Filters use MongoDB query syntax — double-check filter format

Backup Issues

Backup creation fails

pc index describe -n my-index
# Backups are only supported for serverless indexes in "Ready" state

Can't find backup ID

pc backup list --index-name my-index
# Use the UUID (e.g. c84725e5-...) not the name for restore/delete

---

Best Practices

Use the right auth method

• Interactive dev: pc login
• CI/CD pipelines: service accounts
• Quick testing: pc api-key create -n "my-key" --store

Check status before operating

pc auth status
pc target --show
pc index describe -n my-index

Use JSON output for scripts

pc index list -j | jq -r '.[] | .name'

Preview destructive operations

pc index vector update -n my-index \
  --filter '{"genre":{"$eq":"old"}}' \
  --metadata '{"genre":"new"}' \
  --dry-run

Protect production indexes

pc index create -n prod-index -d 1536 -m cosine -c aws -r us-east-1 \
  --deletion-protection enabled

Automate backups

pc backup create -i my-index -n "daily-backup-$(date +%Y%m%d)"