AutoGineer
Generated banner for Pinecone CLI
Generated logo for Pinecone CLI

Pinecone CLI

PineconeOfficialPublished by Pinecone

  • Skill
  • Tool integration
  • Cloud and DevOps
  • MIT
  • No issues found
Download ZIP

From the author

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.
— the description by Pinecone

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The Pinecone CLI (pc) provides a comprehensive command-line interface for interacting with Pinecone resources. Unlike other integration methods, the CLI supports all index types—including standard, integrated, and sparse—and enables full control over vector operations, backups, namespaces, and project management. It is designed for developers who require batch processing, CI/CD automation, and direct terminal-based management of their vector database infrastructure.

What it does

  • Create, list, describe, and configure Pinecone indexes.
  • Perform vector operations including upsert, query, fetch, update, and delete.
  • Manage namespaces and perform index backups and restores.
  • Support batch processing of vector data from JSON and JSONL files.
  • Enable CI/CD automation via service account authentication.
  • Output data in JSON format for integration with shell scripting tools like jq.

When to use it

  • When you need to manage indexes or vector data outside of an application's runtime.
  • When performing bulk data operations or migrations.
  • When automating database tasks within CI/CD pipelines.
  • When working with index types or operations not supported by other integration tools.
  • When you need to perform destructive operations with a dry-run preview.

Advantages

  • Full feature parity with Pinecone's API capabilities.
  • Supports all index types including sparse and standard indexes.
  • Enables scriptable workflows using JSON output.
  • Provides robust tools for production safety, such as deletion protection and dry-run updates.
  • Optimized for both interactive development and automated environments.

Usage examples

“Create a new serverless index named my-index with 1536 dimensions.”
The CLI executes the index creation command, setting up the index with specified parameters like cosine metric and cloud provider.
“Upsert vectors from a local JSON file into my-index.”
The CLI reads the vectors from the specified file and performs a batch upsert operation into the target index.
“Query my-index using a specific vector and filter results by metadata.”
The CLI returns the top-k matches based on the provided vector values and metadata filter criteria.
“List all index names in JSON format for a script.”
The CLI outputs the list of indexes as a JSON array, which can be piped into jq to extract specific fields.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/pinecone-io/pinecone-cli/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip pinecone-cli.zip -d .agents/skills

Documentation by Pinecone

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

CLIMCP
Index typesAll (standard, integrated, sparse)Integrated only
Vector ops (upsert, query, fetch, update, delete)✅❌
Text search on integrated indexes✅✅
Backups, namespaces, org/project mgmt✅❌
CI/CD / scripting✅❌

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

TaskCommand
List indexespc index list
Create serverless indexpc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1
Index statspc index stats -n my-index
Upload vectors from filepc index vector upsert -n my-index --file ./vectors.json
Query by vectorpc index vector query -n my-index --vector '[0.1, ...]' -k 10 --include-metadata
Query by vector IDpc index vector query -n my-index --id "doc-123" -k 10
Fetch vectors by IDpc index vector fetch -n my-index --ids '["vec1","vec2"]'
List vector IDspc index vector list -n my-index
Delete vectors by filterpc index vector delete -n my-index --filter '{"genre":"classical"}'
List namespacespc index namespace list -n my-index
Create backuppc backup create -i my-index -n "my-backup"
JSON output (for scripting)Add -j to any command

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

Documentation

Files

references/troubleshooting.md

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)"

Requirements and compatibility

Written for: Claude Code

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Claude Code frontmatter, Needs an API key, Needs a command-line tool

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Pinecone
Publisher
Pinecone (Official)
Source
pinecone-io/skills · skills/pinecone-cli · commit 885dc53
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Pinecone or Pinecone.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download pinecone-cli.zip