The query dynamodb command lets you inspect data in a deployed DynamoDB table directly from the command line. It supports five read-only operations — sample, scan, query, get, and schema — so you can check table structure, look up items by key, or browse data without leaving the terminal.
Use this command as your first tool when you need to verify data in a deployed DynamoDB table. The command resolves your Stacktape DynamoDbTable resource by name and runs read-only operations against the deployed table, so there's no risk of accidental writes.
Usage
The resource name argument must match the name of a DynamoDbTable resource in your Stacktape configuration. If you omit --operation, the command defaults to sample. When --limit is omitted, the command uses a default limit of 100.
CLI reference
stacktape query dynamodb <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.
-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.
--indexstringDatabase Index
Index name. For DynamoDB: secondary index to query. For OpenSearch: index to search.
--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).
--pkstringDynamoDB Partition Key
JSON object with partition key name and value (e.g., '{"id": "123"}').
-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.
--skstringDynamoDB Sort Key
JSON object with sort key name and value (e.g., '{"timestamp": 12345}').
Operations
The query dynamodb command supports five operations. All are read-only.
sample
The sample operation returns items from the table — useful for a quick sanity check that data exists and looks right. This is the default operation when --operation is omitted. Use --limit to control how many items are returned.
schema
The schema operation returns schema information for the table. Run this first when you're unfamiliar with a table — use the returned metadata to choose values for --pk, --sk, or --index.
scan
The scan operation reads items from the table without filtering by key. Use --limit to control how many items are returned (defaults to 100 when omitted). Scans read the table sequentially, so they consume read capacity proportional to the data scanned — keep --limit reasonable on large tables.
query
The query operation fetches items matching a specific partition key, optionally filtered by sort key. Requires --pk with a JSON object mapping the partition key name to its value. Use --sk to narrow results by sort key, and --index to query a global secondary index instead of the primary table.
Query a GSI with a sort key filter:
get
The get operation retrieves a single item by its full primary key (partition key + sort key if the table has one). Requires --pk; use --sk when the table has a composite key. If no item matches, the command prints the result returned by DynamoDB.
Programmatic output
The --agent flag switches to programmatic output mode. With --agent, query dynamodb prints the operation result as a JSON object (with ok, resource, operation, and the operation-specific data) for programmatic consumption by scripts or AI coding agents.
--operation schema first on unfamiliar tables. It returns table metadata you need to choose values for --pk and --sk.Examples
Quickly check if a table has data after a fresh deployment:
Inspect the key schema and indexes before writing a query:
Fetch all items for a specific user:
Get a single item by composite key:
Scan for recent items (up to 10):
Related commands
query sql— run read-only SQL queries against deployed PostgreSQL or MySQL databases.query redis— inspect keys and values in a deployed Redis cache.query opensearch— search and inspect deployed OpenSearch domains.
query dynamodb FAQ
Can I query a global secondary index?
Yes. Pass --index <indexName> with the query operation. The --pk value must match the GSI's partition key, not the table's primary partition key. Run --operation schema first to inspect the table metadata before querying.
What format does --pk expect?
The --pk flag takes a JSON object mapping the key attribute name to its value — for example, '{"userId": "abc-123"}'. The attribute name must match the partition key name in the table's schema. The same format applies to --sk. If the JSON is malformed, the command returns an error asking for valid JSON objects.
What is the default limit for sample and scan?
When --limit is omitted, the command uses a default limit of 100 items, for both sample and scan. Use --limit to request fewer or more items.
Is this command safe to run against production tables?
Yes. All five operations are strictly read-only — the command never writes, updates, or deletes items. Be mindful of scan on large tables: it consumes DynamoDB read capacity units proportional to the data scanned, which could affect performance if your table's provisioned capacity is low. Use --limit to keep scans bounded.
How is this different from aws call, and can I use it on tables not managed by Stacktape?
The aws call command gives raw AWS SDK access and requires you to construct the full DynamoDB API input (including the physical table name and marshalled attribute values). query dynamodb instead resolves your Stacktape resource name to the underlying table and provides higher-level operations like schema and sample, so you can inspect data without knowing the physical table name or DynamoDB API shape. The trade-off: it only accepts a deployed Stacktape resource whose type is dynamo-db-table. For tables outside Stacktape, use aws call with the DynamoDB SDK commands directly.
Does this command need a bastion tunnel or VPC access?
No. DynamoDB is a regional AWS service accessible over the public internet — it does not run inside a VPC. No bastion tunnel is needed, unlike VPC-only resources such as relational databases or Redis caches.