cli

Pinecone CLI

pc is Pinecone on the command line.

⚠️ Note: This CLI is in public preview and does not yet support all features available through the Pinecone API. Please try it out and let us know of any feedback. You'll want to upgrade often as we address feedback and add additional features.

Installation

Homebrew (macOS, Linux)

The most convenient way to install the CLI on macOS and Linux is via Homebrew.

If you don't have Homebrew installed, install it first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1. Add the Pinecone tap to your Homebrew configuration:

brew tap pinecone-io/tap

1. Install the Pinecone CLI:

brew install pinecone-io/tap/pinecone

1. Verify the installation:

pc --help

What is a Homebrew tap?

A Homebrew tap is a third-party repository of Homebrew formulas. Our official tap at pinecone-io/homebrew-tap contains the formula needed to install the Pinecone CLI.

Upgrading

To upgrade to the latest version:

brew update
brew upgrade pinecone

Uninstalling

To remove the CLI:

brew uninstall pinecone

To remove the Pinecone tap entirely:

brew untap pinecone-io/tap

Download artifacts from release page (Linux, Windows, macOS)

For users who prefer not to use Homebrew or need specific platform binaries, we provide pre-built binaries for many platforms.

1. Visit the Releases page
2. Download the appropriate binary for your platform and architecture from the "Assets" section.
3. Make the binary executable (Linux/macOS):

   chmod +x pc
   

4. Move to a directory in your PATH (optional but recommended):

   sudo mv pc /usr/local/bin/  # Linux/macOS
   # or on Windows, add the directory to your PATH
   

5. Verify the installation:

   pc --help
   

Supported platforms

• macOS: Intel (x86_64) and Apple Silicon (ARM64)
• Linux: x86_64, ARM64, and i386 architectures
• Windows: x86_64 and i386 architectures

Build from source

To learn about the steps involved in building from source, see CONTRIBUTING

Authentication

There are three ways to authenticate the Pinecone CLI: through a web browser with user login, using a service account, or with an API key.

This table describes the Pinecone operations supported by each authentication method:

• Admin API–related commands (organization and project management, API key operations):

  • pc organization (list, describe, update, delete)
  • pc project (create, list, describe, update, delete)
  • pc api-key (create, list, describe, update, delete)

• Control plane–related commands (index management):

  • pc index (create, list, describe, configure, delete, stats)

• Data plane-related commands (index data management):

  • pc index vector (upsert, query, fetch, list, update, delete)

1. User Login (Recommended for Interactive use)

The standard authentication method for interactive use. Provides full access to the Admin API and control/data plane operations. When authenticated this way, you have access to all organizations associated with the account.

pc auth login

This command:

• Opens your browser to the Pinecone login page
• Automatically sets a target organization and project context
• Grants access to manage organizations, projects, and other account-level resources

View and change your current target:

pc target -s
pc target -o "ORGANIZATION_NAME" -p "PROJECT_NAME"

2. Service account authentication

Use service account client credentials for authentication. Service accounts are scoped to a single organization, but you can manage projects and set a target project context.

# Prompts you to pick a target project from the projects available to the service account
pc auth configure --client-id "YOUR_CLIENT_ID" --client-secret "YOUR_CLIENT_SECRET"

# Specify a target project when configuring the service account
pc auth configure --client-id "client-id" --client-secret "client-secret" --project-id "project-id"

3. API key authentication

Use a project API key directly. Provides access to control/data plane operations only (no Admin API access). If an API key is set directly, it overrides any configured target organization and project context.

pc auth configure --api-key "YOUR_API_KEY"

# alternatively
pc config set-api-key "YOUR_API_KEY"

For more detailed information, see the CLI authentication documentation.

Data plane commands overview

Work with your vector data inside an index. These commands require --index-name and optionally --namespace:

• Ingest and manage records:
  • pc index vector upsert — insert or update vectors from JSON/JSONL
  • pc index vector list — list vectors (with pagination)
  • pc index vector fetch — fetch by IDs or metadata filter
  • pc index vector update — update a vector by ID or update many via metadata filter
  • pc index vector delete — delete by IDs, by filter, or delete all in a namespace
  • pc index vector query — nearest-neighbor search by values or vector ID
• Index statistics:
  • pc index stats — show dimension, vector counts, namespace summary, and metadata field counts (optionally filtered)

Tip: add --json to many commands to get structured output.

Quickstart

After installing the CLI, authenticate with user login or set an API key, verify your auth status, and list indexes associated with your automatically targeted project.

# Option 1: Login via browser (recommended)
pc auth login

# Option 2: Set API key directly
pc config set-api-key "YOUR_API_KEY"

# Verify authentication
pc auth whoami
pc auth status

# Create a serverless index
pc index create --name my-index --dimension 3 --metric cosine --cloud aws --region us-east-1

# List your indexes
pc index list

Working with data

Once you've created an index you can use pc index upsert to begin storing data in Pinecone. There are a variety of ways to get your data into Pinecone through the CLI.

JSON input formats

Many flags accept JSON in three forms:

• Inline JSON for smaller payloads, for example:

  pc index vector fetch --index-name my-index --namespace demo --ids '["vec-1","vec-2"]'
  

• From a file ending in .json, or .jsonl for upsert operations:

  pc index vector upsert --index-name my-index --namespace demo --body ./vectors.json
  

• From stdin with -:

  cat vectors.json | pc index vector upsert --index-name my-index --namespace demo --body -
  

Stdin can only be used with one flag at a time.

JSON schemas

For commands that accept a --body JSON payload, the CLI defines types in the vector package that depend on types in the go-pinecone SDK. These structs can be useful for shaping your data for ingestion:

• UpsertBody — and array of pinecone.Vector objects (see https://pkg.go.dev/github.com/pinecone-io/go-pinecone/v5/pinecone#Vector)
• QueryBody — fields: id, vector, sparse_values (see https://pkg.go.dev/github.com/pinecone-io/go-pinecone/v5/pinecone#SparseValues), filter, top_k, include_values, include_metadata
• FetchBody — fields: ids, filter, limit, pagination_token
• UpdateBody — fields: id, values, sparse_values (see https://pkg.go.dev/github.com/pinecone-io/go-pinecone/v5/pinecone#SparseValues), metadata, filter, dry_run

Create a file named vectors.json with an array of vectors with a dimension matching you index:

{
  "vectors": [
    {
      "id": "vec-1",
      "values": [0.1, 0.2, 0.3],
      "metadata": { "genre": "sci-fi", "title": "Voyager" }
    },
    {
      "id": "vec-2",
      "values": [0.3, 0.1, 0.2],
      "metadata": { "genre": "fantasy", "title": "Dragon" }
    }
  ]
}

Alternatively, you can upsert using a JSONL file where each line is a vector object:

{"id":"vec-1","values":[0.1,0.2,0.3],"metadata":{"genre":"sci-fi","title":"Voyager"}}
{"id":"vec-2","values":[0.3,0.1,0.2],"metadata":{"genre":"fantasy","title":"Dragon"}}

# Upsert vectors into the index via JSON or JSONL
pc index vector upsert --index-name my-index --namespace my-namespace --body ./vectors.jsonl

# List vectors
pc index vector list --index-name my-index --namespace my-namespace

# Fetch a vector by ID
pc index vector fetch --index-name my-index --namespace my-namespace --ids '["vec-1"]'

# Query by dense vector values
pc index vector query --index-name my-index --namespace my-namespace --vector '[0.1,0.2,0.3]' --top-k 3 --include-metadata

# Query by existing vector ID
pc index vector query --index-name my-index --namespace my-namespace --id vec-1 --top-k 3