AWS CLI command history from zero: purpose, boundaries, and first CLI inventory

Part 1130 of AWS from Zero.

What we are learning

AWS CLI command history answers the debugging question your shell history cannot: not just which command you typed, but what the CLI actually did with it — the API calls it made, the requests it sent, and the return code it produced. The feature is off by default. You opt in by setting cli_history to enabled in the ~/.aws/config file, which the documentation does with one command: aws configure set cli_history enabled. From then on, the CLI records commands locally, and the aws history command group gives you two readers: list shows previously run commands with their command_id, date, arguments, and return code, and show expands one command into its detailed event timeline.

The planes are worth naming. The control plane is the cli_history setting in your config file plus the optional AWS_CLI_HISTORY_FILE environment variable. The data plane is the local SQLite database at ~/.aws/cli/history/history.db by default, or at the path named by that environment variable. Nothing about this feature is an AWS service: it has no ARN or service API.

That locality defines what history should not be used for. It is not an audit or compliance trail. It starts recording only after you enable it, the default database can contain commands from multiple profiles on the same machine, and anyone with file access can edit or delete it. Use appropriately configured AWS CloudTrail trails or event data stores for account-side audit evidence; local history does not replace them. History is a personal debugging instrument, and AWS documents that the database can contain complete command parameters plus API request and response data, so protect it as sensitive data.

Before you run it

export AWS_PROFILE="aws-zero-sandbox"
export AWS_REGION="ap-south-1"
aws sts get-caller-identity
aws configure get region

Any authenticated sandbox profile works. The history subcommands need no IAM permissions because they read local files; the identity check is this lesson's only network call. History is not regional, has no service quota, and has no service-side eventual consistency. The privacy consideration flows the other way: once enabled, history captures details of recorded commands, so enable it on shared machines deliberately, not by habit.

Cost note: this lesson is read-only and free. aws history subcommands read local files, aws sts get-caller-identity has no charge, and no AWS resource is created.

The command

aws configure get cli_history
echo $?

This is the honest first inventory: is recording on for this profile? The command reads the cli_history key from the active profile's section of the config file. On a profile that never enabled the feature, it prints nothing and exits with code 1 — a meaningful reading, not an installation failure. If it prints enabled and exits 0, recording is active, but the database might not exist yet if no eligible command has completed since enablement.

Inspect the result

aws history list
echo $?

Now read the data plane directly. If recording was never enabled, the CLI reports the empty state explicitly and exits with code 255:

Could not locate history. Make sure cli_history is set to enabled in the ~/.aws/config file

That pair — an absent cli_history setting and no database at the resolved history path — is a complete, consistent empty state. If instead list prints rows, each row's command_id is the handle the next lessons will feed to aws history show. Reads are local and immediate; there is no eventual-consistency wait after a recorded command finishes.

One tiny variation

aws configure get default.cli_history
echo $?

Only the section changed: this reads the default profile's setting instead of the sandbox profile's. Checking both matters on real machines, because the setting is written into whichever profile section was active when someone ran the enable command. An enabled under default but not under your sandbox profile explains why recordings appear or vanish when you switch profiles.

Common mistake

Running aws history list immediately after hearing about the feature and treating the Could not locate history failure, exit code 255, as a broken installation. The error text itself contains the diagnosis and the remedy: recording is opt-in, and the CLI is telling you the config file has no cli_history = enabled line. Verify with the control-plane read: aws configure get cli_history returning empty with exit code 1 confirms the setting is absent, so there is nothing for list to find. The fix belongs to the next lessons, where we enable recording deliberately in the sandbox profile and then clean it up.

Cleanup

aws configure get cli_history
echo $?

This lesson only read state, so cleanup is a final check that nothing changed: the setting read should match your first run, and no history store was created. When later lessons do enable recording, their cleanup will disable it and deal with the recorded files explicitly.

Where this goes later

Next: AWS CLI command history: Regions, endpoints, IAM, quotas, pricing, and cleanup model.