pinecone-cli

Pinecone CLI（pc）

从终端管理 Pinecone。对于跨所有索引类型执行向量操作，CLI 尤其有用——MCP 目前无法做到这一点。

CLI 与 MCP 对比

	CLI	MCP
索引类型	全部（标准、集成式、稀疏）	仅集成式
向量操作（upsert、query、fetch、update、delete）	✅	❌
在集成式索引上进行文本搜索	✅	✅
备份、命名空间、组织/项目管理	✅	❌
CI/CD / 脚本编写	✅	❌

---

设置

安装（macOS）

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

其他平台（Linux、Windows）——从 GitHub Releases 下载。

身份验证

# 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

检查状态：pc auth status · pc target --show

Agent 会话须知：如果需要在 Agent 循环中运行 pc login，浏览器身份验证链接可能无法正确显示。最好在启动 Agent 会话之前完成身份验证。直接在终端中运行 pc login，完成身份验证后再调用 Agent。

对 CLI 进行身份验证不会设置 PINECONE_API_KEY

pc login 只对 CLI 工具本身进行身份验证——不会在环境中设置 PINECONE_API_KEY。使用 Pinecone SDK 的 Python 脚本、Node.js SDK 和其他工具需要单独设置 PINECONE_API_KEY。

使用 CLI 创建密钥并一步导出：

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

如果没有 jq：运行 pc api-key create --name agent-sdk-key --json，然后手动复制 "value" 字段。

---

常用命令

任务	命令
列出索引	pc index list
创建无服务器索引	pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1
查看索引统计信息	pc index stats -n my-index
从文件上传向量	pc index vector upsert -n my-index --file ./vectors.json
按向量查询	pc index vector query -n my-index --vector '[0.1, ...]' -k 10 --include-metadata
按向量 ID 查询	pc index vector query -n my-index --id "doc-123" -k 10
按 ID 获取向量	pc index vector fetch -n my-index --ids '["vec1","vec2"]'
列出向量 ID	pc index vector list -n my-index
按筛选条件删除向量	pc index vector delete -n my-index --filter '{"genre":"classical"}'
列出命名空间	pc index namespace list -n my-index
创建备份	pc backup create -i my-index -n "my-backup"
输出 JSON（用于脚本编写）	在任意命令后添加 -j

---

可执行的实用操作

使用自定义向量查询（不仅限于文本）

与 MCP 不同，CLI 支持使用原始向量值查询任意索引——当你在外部生成嵌入（OpenAI、HuggingFace 等）时，这很有用：

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

将嵌入直接传入查询

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

预览批量元数据更新

# 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"}'

备份和恢复

# 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

在 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

使用 JSON 输出编写脚本

# 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

---

参考文件

• 完整命令参考 — 所有命令及其标志和示例
• 故障排除与最佳实践

文档

• CLI 快速入门
• 命令参考
• 身份验证
• 目标上下文
• GitHub Releases