The query opensearch command runs read-only queries against a deployed OpenSearch domain directly from your terminal. Use it to list indices, check document counts, inspect field mappings, retrieve individual documents, or search with Query DSL — without setting up a separate OpenSearch client or dashboard.
Usage
The command takes the domain's resource name as a positional argument (query opensearch <resource-name>) and always requires --stage and --region. The resource name must match an OpenSearch domain resource defined in your Stacktape configuration. Additional flags depend on the operation.
Operations
The --operation flag selects what kind of query to run. Five operations are available: indices, mapping, count, get, and search. If omitted, the command defaults to indices.
indices
Lists all indices in the OpenSearch domain. This is the default operation and the best starting point when exploring an unfamiliar domain. No additional flags are needed.
mapping
Returns the field mapping for a specific index — useful for understanding the index schema before writing search queries. Requires --index.
count
Returns the document count. You can pass --index to count documents in a specific index; omit it to count across all indices.
Count across the entire domain (no --index):
get
Retrieves a single document by ID. Requires both --index and --id.
search
Runs an OpenSearch Query DSL search. Requires --query with a valid JSON string. You can optionally scope the search to a specific index with --index and control result count with --limit (defaults to 10).
Search within a specific index with a limited result set:
The --query flag accepts OpenSearch Query DSL as a JSON string. The command parses the JSON before sending it — malformed JSON is rejected with Invalid JSON in --query and the hint Provide valid OpenSearch query DSL JSON. On Windows, escape inner double quotes with backslashes. On Linux/macOS, wrap the entire value in single quotes.
Agent mode
When running with --agent, the command prints a structured JSON object containing ok, resource, operation, and the operation result. This makes it suitable for programmatic consumption by AI coding assistants and automation scripts.
For automation, prefer --agent. The global --output-format flag is documented in the flags reference below.
Flags reference
stacktape query opensearch <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.
--idstringDocument ID
ID of the document to retrieve (for OpenSearch get operation).
--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).
-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.
--querystringLogs Query
CloudWatch Logs Insights query string. Example: "fields @timestamp, @message | filter @message like /ERROR/ | limit 50"
--quietbooleanQuiet
Hide progress, banners, success messages and hints. Command output, warnings and errors are still printed.
Examples
Check what indices exist
Start here when exploring an unfamiliar OpenSearch domain. The indices operation is the default, so --operation can be omitted.
Inspect field mappings for an index
Useful for understanding the schema before writing search queries.
Count all documents in the domain
Omit --index to get a total count across every index.
Count documents in a specific index
Pass --index to scope the count.
Retrieve a specific document by ID
Run a full-text search
The --query flag takes OpenSearch Query DSL as a JSON string. This example searches for error-level log entries across the logs index.
Match all documents in an index
Use agent mode for automation
Parse the JSON result programmatically in a CI pipeline or AI coding assistant.
Related commands
query sql— run read-only SQL queries against a deployed relational database.query dynamodb— query a deployed DynamoDB table.query redis— query a deployed Redis cache.aws call— execute read-only AWS SDK commands against any deployed resource.logs— fetch and analyze logs from deployed resources.
query opensearch FAQ
Which flags does each operation require?
The mapping operation requires --index. The get operation requires both --index and --id. The search operation requires --query. For indices, no additional flags are needed. For count, --index is optional — omit it to count across all indices.
Do I need a bastion host to query OpenSearch?
No. The command reads the deployed domain endpoint from the stack, connects over HTTPS, and authenticates with the stack's read-only debug role. The role can send only GET and HEAD requests to the stack's own domains, so the command sends searches as GET with the query in the request body. OpenSearch refuses the role any other request, such as indexing, updating or deleting documents. The command also refuses an --index that contains / or starts with _, since that would reach another endpoint rather than an index. When the stack has no such role or it cannot be assumed, the command fails instead of using your configured AWS credentials. Unlike query sql or query redis, query opensearch does not accept a --bastion-resource flag.
What format does the --query flag expect?
The --query flag accepts a JSON string containing an OpenSearch Query DSL query body. The command parses the JSON before sending it. If the JSON is malformed, the command rejects it with Invalid JSON in --query and the hint Provide valid OpenSearch query DSL JSON. On Windows, escape inner double quotes with backslashes; on Linux/macOS, wrap the entire value in single quotes.
How is query opensearch different from OpenSearch Dashboards?
query opensearch is a CLI tool for quick, ad-hoc inspection from your terminal — checking an index exists, verifying document counts, or running a one-off search. OpenSearch Dashboards provides a full web UI with visualizations, saved queries, and interactive exploration. Use the CLI for fast debugging; use Dashboards for ongoing analytics and dashboard building.
What happens if the OpenSearch domain is not deployed?
The command looks up the domain endpoint from the deployed stack. If the resource does not exist in the stack or the domain is not yet provisioned, the command fails with an error indicating it could not retrieve the OpenSearch endpoint. Verify the stack is deployed and the --resource-name matches a resource in your configuration.