upstash-cli

优先使用可用的 MCP 服务

如果当前会话中有 Upstash MCP 工具，请调用它们，而不是通过 shell 调用 CLI。它们已完成身份验证，涵盖的功能也相同——创建和检查 Redis 数据库、运行 Redis 命令、查看用量统计、备份、Vector 和 Search 索引、Blob 存储桶、QStash 计划和消息、DLQ 以及日志。安装 Upstash 插件会注册托管服务 https://mcp.upstash.com/mcp。

如果当前会话中没有 MCP，或者工作本质上属于 shell 操作（例如 CI 步骤、配置脚本，或将 JSON 管道传递给其他命令），请使用 CLI。

Upstash CLI（upstash）通过 Upstash Developer API 管理 Upstash 服务。所有命令均为非交互式，并在 stdout 上输出 JSON。错误会以 { "error": "..." } 的形式写入 stderr，退出代码为 1。

安装

npm i -g upstash

或者无需安装，直接运行单条命令：npx upstash <command>。

将编码 Agent 连接到 Upstash

upstash setup 可通过一个步骤将编码 Agent 连接到 Upstash。Claude Code、Codex、Cursor 和 Gemini CLI 会安装 Upstash 插件（Upstash 技能以及远程 MCP 服务）。VS Code、GitHub Copilot CLI 和 OpenCode 会在其配置中添加远程 MCP 服务（https://mcp.upstash.com/mcp）和 upstash 技能。MCP 服务会在首次使用时通过 OAuth 登录，因此 setup 绝不会将 API 密钥写入 Agent 的配置。

在终端中，用户可以运行 npx upstash：在终端中不带参数运行时，会启动 upstash setup 并询问要设置哪些 Agent。在终端之外，单独运行 upstash 只会显示帮助信息，因此从 Agent 或脚本中调用时，请使用 upstash setup 并添加 --yes 和 Agent 标志：

npx -y upstash setup --yes --claude             # or --codex, --cursor, --gemini, --vscode, --copilot, --opencode
npx -y upstash setup --yes --cursor --mode mcp  # remote MCP server + skill instead of the plugin
npx -y upstash setup --yes --claude --project   # this project instead of the user config
npx -y upstash setup --yes --dry-run            # show what would change; without agent flags, --yes covers every detected agent

使用 --project 时，Claude Code 会在项目级别安装插件；Codex、Cursor 和 Gemini CLI 插件只能按用户安装，因此它们会改为添加项目级 MCP 配置和技能。再次运行 setup 会更新已安装的内容。之后需要重启或重新加载 Agent（在 Claude Code 中运行 /reload-plugins；在 Cursor 中选择 Developer: Reload Window）。

身份验证

推荐做法：每台机器运行一次 upstash login。系统会提示输入邮箱和 Developer API 密钥（在 https://console.upstash.com/account/api 创建），验证后将其保存到 ~/.config/upstash/config.json。

upstash login

其他方式——使用环境变量（也会自动加载当前工作目录中的 .env），或在命令中直接指定 --email / --api-key，或使用 --env-path <path> 指定特定的 .env 文件：

export [email protected]
export UPSTASH_API_KEY=your_api_key

优先级：标志 > 环境变量 > .env > 已保存的配置。尽可能为 Agent 使用只读 API 密钥——修改操作会在 API 处失败，与在控制台中的情况相同。

资源 ID 标志

标志	产品
--db-id <id>	Redis
--index-id <id>	Vector、Search
--qstash-id <id>	QStash
--bucket-id <id>	Blob
--team-id <id>	Team

Redis

upstash redis list
upstash redis get --db-id <id> [--hide-credentials]
upstash redis create --name <name> --region <region> [--read-regions <r1> <r2>]
upstash redis delete --db-id <id> [--dry-run]
upstash redis rename --db-id <id> --name <new-name>
upstash redis reset-password --db-id <id>
upstash redis stats --db-id <id>

upstash redis enable-tls --db-id <id>
upstash redis {enable,disable}-eviction --db-id <id>
upstash redis {enable,disable}-autoupgrade --db-id <id>
upstash redis change-plan --db-id <id> --plan <free|payg|pro|paid>
upstash redis update-budget --db-id <id> --budget <cents>
upstash redis update-regions --db-id <id> --read-regions <r1> <r2>
upstash redis move-to-team --db-id <id> --team-id <id>

区域——AWS：us-east-1、us-east-2、us-west-1、us-west-2、ca-central-1、eu-central-1、eu-west-1、eu-west-2、sa-east-1、ap-south-1、ap-northeast-1、ap-southeast-1、ap-southeast-2、af-south-1。GCP：us-central1、us-east4、europe-west1、asia-northeast1。

Redis 备份

upstash redis backup list --db-id <id>
upstash redis backup create --db-id <id> --name <name>
upstash redis backup delete --db-id <id> --backup-id <id> [--dry-run]
upstash redis backup restore --db-id <id> --backup-id <id>
upstash redis backup {enable,disable}-daily --db-id <id>

Redis exec（REST，而非 Developer API 密钥）

upstash redis exec --db-url <url> --db-token <token> SET key value
upstash redis exec --db-url <url> --db-token <token> --json '["SET","key","value"]'

--db-url / --db-token 会回退使用 UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN。通过 upstash redis get --db-id <id> 中的 endpoint 和 rest_token 获取这两项。

Team

upstash team list
upstash team create --name <name> [--copy-cc]
upstash team delete --team-id <id> [--dry-run]
upstash team members --team-id <id>
upstash team add-member --team-id <id> --member-email <email> --role <admin|dev|finance>
upstash team remove-member --team-id <id> --member-email <email> [--dry-run]

Vector

upstash vector list
upstash vector get --index-id <id>
upstash vector create --name <name> --region <region> --similarity-function <fn> --dimension-count <n> [--type payg] [--index-type <type>] [--embedding-model <m>] [--sparse-embedding-model <m>]
upstash vector delete --index-id <id> [--dry-run]
upstash vector rename --index-id <id> --name <new-name>
upstash vector reset-password --index-id <id>
upstash vector set-plan --index-id <id> --plan <free|payg|fixed>
upstash vector transfer --index-id <id> --target-account <id>
upstash vector stats                             # aggregate across all indexes
upstash vector index-stats --index-id <id> [--period <1h|3h|12h|1d|3d|7d|30d>]

区域：eu-west-1、us-east-1、us-central1。相似度：COSINE、EUCLIDEAN、DOT_PRODUCT。索引类型：DENSE、SPARSE、HYBRID。稠密模型：BGE_SMALL_EN_V1_5、BGE_BASE_EN_V1_5、BGE_LARGE_EN_V1_5、BGE_M3。稀疏模型：BM25、BGE_M3。对于使用托管嵌入的 HYBRID，请设置 --dimension-count 0。

Search

upstash search list
upstash search get --index-id <id>
upstash search create --name <name> --region <region> --type <free|payg|fixed>
upstash search delete --index-id <id> [--dry-run]
upstash search rename --index-id <id> --name <new-name>
upstash search reset-password --index-id <id>
upstash search transfer --index-id <id> --target-account <id>
upstash search stats
upstash search index-stats --index-id <id> [--period <1h|3h|12h|1d|3d|7d|30d>]

区域：eu-west-1、us-central1。

QStash

upstash qstash list                              # run first; maps region → id
upstash qstash get --qstash-id <id>
upstash qstash rotate-token --qstash-id <id>
upstash qstash set-plan --qstash-id <id> --plan <paid|qstash_fixed_1m|qstash_fixed_10m|qstash_fixed_100m>
upstash qstash stats --qstash-id <id> [--period <1h|3h|12h|1d|3d|7d|30d>]
upstash qstash ipv4                              # CIDR blocks for allowlisting
upstash qstash move-to-team --qstash-id <id> --target-team-id <id>
upstash qstash update-budget --qstash-id <id> --budget <dollars>    # 0 = no limit
upstash qstash {enable,disable}-prodpack --qstash-id <id>

Blob

运行 upstash blob --help，检查已安装的 CLI 是否包含 Blob 支持。如果没有此命令，请使用控制台管理存储桶，并使用 upstash-blob-js 编写应用代码，直到某个 CLI 版本支持该功能。

upstash blob list
upstash blob get --bucket-id <id> [--hide-credentials]
upstash blob create --name <name> [--visibility <private|public>] [--cors <origin> <origin>]
upstash blob delete --bucket-id <id> [--dry-run]
upstash blob credentials [--bucket-id <id>]

存储桶默认是 private。blob get 会返回存储桶令牌，它是整个存储桶的持有者密钥——如果只需要元数据，请传入 --hide-credentials。

blob credentials 会将存储桶令牌兑换为临时的、限定存储桶范围的 S3 凭证，供 AWS CLI、rclone 或任何 S3 SDK 使用。使用 --bucket-id 时，它会通过 Developer API 读取令牌；不带任何标志时，它会使用 UPSTASH_BLOB_TOKEN，完全不需要账户身份验证。expiresAt 是以 Unix 时间戳（秒） 表示的过期时间（与 Date.now() 比较前需乘以 1000）——请在过期前重新生成，不要缓存。

CREDS=$(upstash blob credentials --bucket-id <id>)
export AWS_ACCESS_KEY_ID=$(echo "$CREDS" | jq -r .accessKeyId)
export AWS_SECRET_ACCESS_KEY=$(echo "$CREDS" | jq -r .secretAccessKey)
export AWS_SESSION_TOKEN=$(echo "$CREDS" | jq -r .sessionToken)

aws s3 cp image.png "s3://$(echo "$CREDS" | jq -r .bucket)/image.png" \
  --endpoint-url "$(echo "$CREDS" | jq -r .endpoint)" --region auto

对象操作不是 CLI 命令——存储桶兼容 S3，因此请将上述凭证与 S3 工具配合使用，或使用 upstash-blob-js 技能中的 TypeScript SDK。

约定

• 将任何输出通过管道传给 jq 以提取字段，例如 upstash redis list | jq '.[].database_id'。
• 对任何 delete 或 remove-member 操作，先使用 --dry-run。
• 如果不需要密钥，在 redis get 和 blob get 中使用 --hide-credentials。