CLI authentication ↗

Documentation Index#

Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt Use this file to discover all available pages before exploring further.

This feature is in public preview.

This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources.

Authentication methods#

User login#

Authenticate through a web browser. The token refreshes automatically and stays valid for up to 120 days (re-auth required after 30 days of inactivity).

pc auth login

The CLI auto-targets your default organization and its first project. Change with pc target -o "my-org" -p "my-project".

Service account#

Authenticate with credentials from a service account.

pc auth configure --client-id "ID" --client-secret "SECRET"

# Or via environment variables
export PINECONE_CLIENT_ID="your-client-id"
export PINECONE_CLIENT_SECRET="your-client-secret"

The CLI auto-targets the service account’s organization. For projects: auto-selects if one exists, prompts if multiple exist, or set manually with pc target -p "my-project".

API key#

Authenticate with an API key. API keys can’t access the Admin API.

pc auth configure --api-key "YOUR_API_KEY"

# Or via environment variable
export PINECONE_API_KEY="your-api-key"

API keys are scoped to a specific project. When set, control/data plane operations use the key’s project, ignoring any target context you’ve set.

Auth priority#

When multiple credentials exist, the CLI chooses based on operation type. Within each credential type, environment variables take precedence over stored configuration.

Control/data plane operations:

1. API key
2. User login token (via managed keys)
3. Service account (via managed keys)

Admin API operations:

1. User login token
2. Service account

User login and service account are mutually exclusive when configured via CLI commands—each clears the other. However, service account env vars don’t clear a stored user login token.

Example scenarios:

• If PINECONE_API_KEY is set, the CLI uses it for control/data plane operations, regardless of any stored API key.
• If you’re logged in via pc auth login and also have PINECONE_CLIENT_ID/PINECONE_CLIENT_SECRET set, the user login token is used for everything—the service account env vars are ignored.
• If you have an API key configured and are also logged in, the API key is used for control/data plane operations, but user login is used for Admin API operations (since API keys can’t access Admin API).

Managed keys#

When using user login or service account (without a default API key), the CLI automatically creates and manages API keys for control/data plane operations. This happens transparently on first use.

• Stored locally: ~/.config/pinecone/secrets.yaml (permissions 0600)
• Stored remotely: Visible in console as pinecone-cli-{id} with origin cli_created

# List locally tracked managed keys
pc auth local-keys list

# Delete managed keys (local + remote)
pc auth local-keys prune

# Delete only CLI-created managed keys
pc auth local-keys prune --origin cli

# Delete only user-created managed keys
pc auth local-keys prune --origin user

# Delete a specific API key by ID
pc api-key delete --id "KEY_ID"

When you run pc api-key create --store for a project that already has a CLI-created managed key, the CLI automatically deletes the old remote key before storing the new one.

Logging out#

pc auth logout

Clears all local auth data: tokens, credentials, API keys, managed keys, and target context.

pc auth logout doesn’t delete managed keys from Pinecone’s servers. Run pc auth local-keys prune first for full cleanup.

Local storage#

Auth data is stored in ~/.config/pinecone/ with 0600 permissions:

Check status#

pc auth status

Shows your current authentication method, target organization and project, token expiration (for user login), and environment configuration.