version: "1.0.1" name: pinecone:cli description: Guide for using the Pinecone CLI (pc) to manage Pinecone resources from the terminal. The CLI supports ALL index types (standard, integrated, sparse) and all vector operations — unlike the MCP which only supports integrated indexes. Use for batch operations, vector management, backups, namespaces, CI/CD automation, and full control over Pinecone resources. argument-hint: install | auth | index [op] | vector [op] | backup | namespace allowed-tools: Bash, Read

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