The query redis command lets you inspect a deployed Redis cache directly from the command line. It supports five read-only operations — keys, get, ttl, info, and type — so you can check cached values, list keys by pattern, or view server stats without setting up a local Redis client or tunnel.
Usage
The resource name argument must refer to a redis resource defined in your Stacktape configuration. The command resolves the cluster's connection details (host, port, password) from the deployed stack automatically.
Operations
The --operation flag selects what to do. If omitted, it defaults to info.
| Operation | What it does | Required flags |
|---|---|---|
info | Returns Redis server information (memory, clients, stats). Optionally filter with --section. | — |
keys | Lists keys matching a glob pattern. --pattern is optional and defaults to *. | — |
get | Returns the value stored at a specific key. | --key |
ttl | Returns the remaining time-to-live (in seconds) for a key. | --key |
type | Returns the data type of a key (string, list, set, hash, zset, etc.). | --key |
All operations are read-only. You cannot write, delete, or modify data through this command.
Accessing VPC-only clusters
Redis caches deployed inside a VPC are not publicly accessible. To reach them from your local machine, pass --bastion-resource to tunnel through a bastion host in your stack. When --bastion-resource resolves a tunnel target, the command starts an SSM port-forwarding session, uses localhost for the query, and closes the tunnel after the query.
If the Redis endpoint is reachable from your machine, omit --bastion-resource. For VPC-only clusters, pass a bastion resource name.
Examples
View server info
Returns the full Redis INFO output.
Use --section to pass a Redis INFO section such as server, memory, or stats. The command passes the section string directly to Redis.
List keys by pattern
Lists keys matching a glob pattern. The --pattern flag is optional and defaults to * (all keys). Use --limit to cap the number of returned keys.
Get a key's value
Check a key's TTL
Returns the remaining time-to-live in seconds. A value of -1 means the key has no expiration; -2 means the key does not exist.
Check a key's type
Query through a bastion tunnel
When your Redis cache is VPC-only, pass --bastion-resource to route the connection through a bastion host.
Agent mode
When running inside an AI coding agent or CI pipeline, pass --agent to switch to agent-oriented output. In agent mode, query redis prints the Redis result as a JSON object containing ok, resource, operation, and the operation-specific result fields. Agent mode also disables interactive terminal UI.
Flags reference
stacktape query redis <resource-name>CLI options-r, --regionrequired"us-east-2" | "us-east-1" | "us-west-1" | "us-west-2" | "ap-east-1" | "ap-south-1" | "ap-northeast-3" | "ap-northeast-2" | "ap-southeast-1" | "ap-southeast-2" | "ap-northeast-1" | "ca-central-1" | "eu-central-1" | "eu-west-1" | "eu-west-2" | "eu-west-3" | "eu-north-1" | "me-south-1" | "sa-east-1" | "af-south-1" | "eu-south-1"AWS Region
The AWS region for the operation. For a list of available regions, see the AWS documentation.
Inside a project whose config declares region, the flag is optional and overrides the config.
--resource-name (positional 1)requiredstringResource Name
The name of the resource as defined in your Stacktape configuration.
-s, --stagerequiredstringStage
The stage for the operation (e.g., production, staging, dev-john). You can set a default stage using the defaults set command. Stage names use lowercase letters, numbers and dashes, with at least 2 characters. The project name, a dash and the stage form the CloudFormation stack name, which can have at most 128 characters. Stacktape shortens an AWS resource name that would be too long and adds a hash.
--aws-accountstringAWS Account
The name of the AWS account to use for the operation. The account must first be connected in the Stacktape Console.
Without it, the account is chosen by --profile, AWS_PROFILE or AWS credentials in environment variables, then by your saved default, then by your organization's only connected account. --aws-account takes precedence over all of them, but AWS credentials in environment variables must then belong to that account.
--bastion-resourcestringBastion Resource Name
The name of the bastion resource as defined in your Stacktape configuration.
-c, --configstringConfig File Path
The path to your Stacktape configuration file, relative to the current working directory.
Without it, Stacktape uses the one stacktape.ts, stacktape.yml, stacktape.yaml or stacktape.js in the working directory. When there are several, the command stops and asks you to choose one with this option.
--cwdstringCurrent Working Directory
The working directory for the operation. All file paths in your configuration will be resolved relative to this directory. By default, this is the directory containing the configuration file.
-h, --helpstringShow Help
If provided, the command will not execute and will instead print help information.
--keystringRedis Key
The key name to operate on.
--limitnumberLimit
Maximum number of items to return.
--log-level"info" | "debug" | "error"Log Level
The level of logs to print to the console.
info: Basic information about the operation.error: Only errors.debug: Detailed information for debugging.
--operationstringDatabase Operation
The operation to perform (varies by database type).
--patternstringRedis Key Pattern
Pattern for matching keys (default: *). Supports glob-style patterns.
-p, --profilestringAWS Profile
The AWS profile to use for the command. You can manage profiles using the aws-profile:* commands and set a default profile with defaults set.
For commands that use a connected AWS account, --profile (or AWS_PROFILE) selects the connected account the profile belongs to, unless --aws-account is set. The command fails if that account is not connected.
--projectstringProject Name
The name of the Stacktape project for this operation.
Commands that target a stack take it from projectName in the project's config when the flag is absent.
--quietbooleanQuiet
Hide progress, banners, success messages and hints. Command output, warnings and errors are still printed.
--sectionstringRedis Info Section
Specific section of Redis INFO output (e.g., server, memory, stats).
Related commands
query dynamodb— query, scan, or inspect DynamoDB tables.query opensearch— search, count, or inspect OpenSearch indices.bastion tunnel— open a persistent tunnel through a bastion host for use with a local Redis client (e.g.,redis-cli). Usequery redisfor quick one-off lookups; usebastion tunnelwhen you need an ongoing local session.