CLI
The cats command line. Commands, arguments, flags, defaults, exit codes and streams are
covered by the compatibility contract. cats --help and
cats <command> --help are the reference for each command's arguments and flags.
Commands
| Command | Purpose |
|---|---|
cats init |
Bootstrap a new cats.yaml and the other files a project needs. A no-op when cats.yaml exists unless --force is given |
cats validate |
Validate cats.yaml syntax and schema, and measure each account's CloudFormation template against the 51,200-byte limit (offline, no credentials). Regenerates .schema.json |
cats generate-types |
Generate cats_types.py with Protocol classes for typed fixtures |
cats test [args]... |
Run the CATS tests with pytest, defaulting to pytest -vv -ra. Any arguments replace the defaults and go to pytest |
cats infra deploy |
Deploy CATS infrastructure via CloudFormation to one or more accounts, or --all, in parallel |
cats infra destroy |
Destroy CATS infrastructure via CloudFormation. No confirmation prompt |
cats infra targets |
Show the accounts and network targets that deploy and destroy would affect |
cats infra status |
Show the CloudFormation stack status and the deploying CATS version per account |
cats infra show-template |
Show or export the CloudFormation template that would be deployed |
cats run account-info |
Runtime metadata from the stack outputs for one account: targets, handlers, EC2 DNS, tags, deployed CATS version |
cats run http-call |
HTTP call from an account's target network segment to a host and port |
cats run tcp-call |
TCP call from an account's target network segment to a host and port |
cats run udp-call |
UDP send from an account's target to a host and port |
cats run shell |
Run shell commands on an account's target EC2 instance via SSM. Requires allow_shell: true at deploy time |
cats run receive-s3 |
Poll the receiving account's response bucket for a UDP receipt |
cats run write-profile |
Write an AWS profile that assumes an account's role from your current identity. Writes no credential |
cats prompts overview |
What CATS is and how it works, for an AI agent |
cats prompts setup |
How to configure and deploy CATS, for an AI agent |
cats prompts testing |
How to write CATS tests, for an AI agent |
cats prompts agentic |
Profile for agents connected to CATS over MCP |
cats mcp |
Start CATS as a Model Context Protocol server. Requires the mcp extra |
cats run output
cats run is the shell surface over deployed infrastructure: every subcommand takes flags in
and prints one JSON object on stdout. Nothing is cached between invocations. The shapes below
are what this release emits; the body is not covered
by the compatibility contract, so read the keys you need and tolerate ones you do not know.
The same operations are MCP tools, listed in MCP.
| Subcommand | Emits |
|---|---|
account-info |
{"name", "account_id", "tags", "deployed_version", "targets"}. targets maps each target name to {"vpc_id", "subnet_ids", "enabled_handlers", "ec2": {"dns_name", "instance_id"}, "lambda": {"probe_lambda_name"} or null} |
http-call, tcp-call |
{"result", "reason", "http_status"}, every key always present and null when absent. result values are defined in Network Testing; http_status is the code on HTTP SUCCESS and null for TCP |
udp-call |
{"result", "reason", "correlation_id"}; result is SENT, DNS_FAILURE or FAILURE. When --host is a CATS listener, pass --receiving-account so the datagram carries that account's receipt token; without it the listener drops the datagram. On SENT, pair correlation_id with receive-s3 on the receiving account |
receive-s3 |
{"received": true \| false} |
shell |
{"stdout", "stderr", "exit_code", "duration_ms", "stdout_truncated", "stderr_truncated"}; needs allow_shell: true at deploy |
write-profile |
{"profile_name", "profile_file", "role_arn", "parent"} after writing the profile. profile_file is the real path written; parent is the source_profile = ... or credential_source = ... line that names the identity the role is assumed from |
Every failure cats run detects itself is {"error": "..."} on stderr with the exit code
above; a usage error typer detects (unknown flag, bad --port) is typer's usage text.
write-profile
Writes an AWS profile that assumes a test role, into an AWS config file (~/.aws/config by
default), so the aws CLI, an SDK or an agent's AWS tool can act as the role. The profile holds
the role's ARN and the identity to assume it from — never a credential.
cats run write-profile --account prod # writes [profile cats-prod-default]
aws sts get-caller-identity --profile cats-prod-default
[profile cats-prod-default]
role_arn = arn:aws:iam::111111111111:role/CATS-test-infra-prod-default-test-role
source_profile = my-parent
role_session_name = cats-profile
region = us-east-1
- The default name is
cats-<account>-<role>; a custom--profile-namemust start withcats-, so the command never overwrites a profile it did not create. The file must be an AWS config file (or not exist yet); anything else is refused untouched. --profile-filebeatsAWS_CONFIG_FILEbeats~/.aws/config. A new file is created0600; an existing file keeps its permissions and every section other than the ones CATS owns, byte for byte. A file that already holds the stanza is not rewritten.- The parent line is derived from how CATS itself resolved AWS credentials: a named profile (including SSO or a chained role) becomes
source_profile; environment, instance-role or container credentials becomecredential_source = Environment | Ec2InstanceMetadata | EcsContainer; web-identity credentials taken from the environment are materialized as acats-parent-<account>profile the role's profile sources. - The AWS CLI and every SDK assume and refresh the role themselves, so the profile does not expire and
export AWS_PROFILE=cats-prod-defaultis safe.
Note
The profile contains no credential. When the AWS CLI assumes the role through it, the CLI
caches the resulting temporary credentials under ~/.aws/cli/cache; that is the CLI's own
behavior for any role_arn profile. If you need the raw keys on stdout (for eval or a
container --env-file), the AWS CLI prints them: aws configure export-credentials
--profile cats-prod-default --format env.
Exit codes
The same four codes on every command:
| Code | Meaning | Example |
|---|---|---|
0 |
Success | cats infra status reporting every account, including one that is "not deployed" |
1 |
The operation ran and failed | cats infra deploy --all where one account's stack rolled back; cats infra status where one account's role could not be assumed; cats run http-call where the AWS API call failed |
2 |
Usage or configuration error | An unknown flag; a missing required option; cats validate on an invalid cats.yaml; --config pointing at a path that is not a file |
130 |
Interrupted | Ctrl+C during cats infra deploy |
A batch (--all, or several account names) that mixes usage and operational failures
reports 2: the configuration is the thing to fix first, and every failure is on stderr
either way.
cats test is the one exception: once it has handed over to pytest it returns pytest's
exit code unchanged (0 all passed, 1 tests failed, 2 interrupted, 3 internal error,
4 usage error, 5 no tests collected). pytest runs as a child process. A SIGTERM or
SIGHUP sent to cats test is passed to it unchanged, so the run ends as pytest ends under
the same signal: pytest handles neither, so it stops at once, finalizers do not run and no
report is written; cats test then returns 128 + N, as a shell reports a child ended by
signal N (143 for SIGTERM). GNU timeout, a terminal hangup and a shell-executor CI
runner signal the whole process group, so pytest receives the signal directly in any case. To
keep the reports when a run is cut short, interrupt the process group with SIGINT, which both
processes handle as Ctrl+C: timeout --signal=INT 30m cats test (timeout itself then exits
124; add --preserve-status to get cats test's 2), or kill -INT -- -<pgid>. The kill
form needs SIGINT not ignored: a background job of a non-interactive shell starts with it
ignored, and the signal then has no effect: the run continues to its normal end, so prefer
timeout, which installs its own handler and starts cats test with the default. A SIGINT
sent to the cats process alone does not reach pytest.
Streams
Results to stdout, diagnostics to stderr.
- A result is what the command exists to produce: the JSON from
cats run, the template fromcats infra show-template, the tables fromcats infra statusandcats infra targets, the prompt text fromcats prompts, the profile location fromcats run write-profile. - A diagnostic is everything else: failure text, warnings, progress, and the
{"error": ...}documentcats runemits on failure.
cats infra deploy --all 2>errors.log therefore captures every failure message, and
cats validate >/dev/null still shows why it failed.
An expected failure (a CATS error, or an AWS SDK error such as no credentials, an expired
token or an unreachable endpoint) is one FAIL <message> line; cats run reports the same
failures as its {"error": ...} document. CATS_DEBUG=1 lets an AWS SDK error, including one
CATS has wrapped, propagate with its traceback instead, for the case where the request itself
was wrong.
The config option
Every command that reads cats.yaml takes --config <path>, defaulting to the
CATS_CONFIG environment variable and then ./cats.yaml. The short form is -c on every
command except cats test, which passes unknown arguments through to pytest, and pytest
owns -c FILE. A --config path that is not a file is a usage error (exit 2), never an
empty configuration, and so is an absent default: cats infra ... and cats generate-types
refuse to run when neither CATS_CONFIG nor ./cats.yaml names an existing file.