A fast, output-compatible Rust reimplementation of the AWS CLI v2
Install · Usage · Performance · Development · Releases
awsr takes the command line of the AWS CLI v2 and prints the same output. Against a local stub endpoint, awsr sts get-caller-identity takes 6.4 ms where aws takes 646 ms on the same machine; a real call adds the same network round trip to both (Performance).
On Linux x86_64 (other platforms: Install):
$ curl -L https://github.com/conao3/rust-awscli/releases/latest/download/awsr-x86_64-unknown-linux-musl.tar.gz | tar xz
$ ./awsr sts get-caller-identityThe same command against the local stub endpoint of bench/:
$ time aws ec2 describe-regions --output table > aws.txt
real 0.935 s
$ time awsr ec2 describe-regions --output table > awsr.txt
real 0.009 s
$ cmp aws.txt awsr.txt && echo identical
identical- Same output. Your scripts,
--queryexpressions, and--outputformats give the same bytes they give withaws. Differential testing runs both CLIs on the operations of all services and compares what they print. - Its own name. What
awsrsays about itself namesawsr:--versionprintsawsr/<version> (aws-cli/<reference version> compatible) <system>/<release> <machine>, and the usage lines, theawsr: [ERROR]:prefix of error messages, and the command lines of the help pages nameawsr. The text of messages and help pages is the reference's. - All services.
awsrembeds the botocore service models of a pinned AWS CLI release (models/VERSION) and interprets them at run time. You can call any service and operation of that release asawsr <service> <operation>.
awsr is not an official AWS product.
The GitHub releases carry binaries for Linux (x86_64, x86_64 musl, aarch64) and macOS (x86_64, aarch64). Each archive holds one awsr executable.
$ curl -L https://github.com/conao3/rust-awscli/releases/latest/download/awsr-<target>.tar.gz | tar xz<target> is one of x86_64-unknown-linux-gnu, x86_64-unknown-linux-musl, aarch64-unknown-linux-gnu, x86_64-apple-darwin, and aarch64-apple-darwin.
$ nix profile install github:conao3/rust-awscli$ cargo install awsrThe crate takes the vendored models from three data crates (awsr-models, awsr-models-services-a-l, and awsr-models-services-m-z, versioned as the reference release). cargo install formats no help page at build time, so awsr formats each page with the installed groff on first use.
Replace aws with awsr:
$ awsr sts get-caller-identity
$ awsr dynamodb list-tables --output table
$ awsr ec2 describe-instances --query 'Reservations[].Instances[].InstanceId' --output textawsr reads the same ~/.aws/config, ~/.aws/credentials, SSO token cache, and environment variables as the AWS CLI.
bash (~/.bashrc):
if command -v aws_completer > /dev/null; then
complete -C aws_completer awsr
fizsh (~/.zshrc):
autoload -Uz bashcompinit && bashcompinit
if command -v aws_completer > /dev/null; then
complete -C aws_completer awsr
fifish (~/.config/fish/completions/awsr.fish, or ~/.config/fish/config.fish):
if type -q aws_completer
function __awsr_completer
set -lx COMP_LINE (commandline -pc)
set -lx COMP_POINT (string length $COMP_LINE)
aws_completer | tr -d ' '
end
complete -c awsr -f -a "(__awsr_completer)"
end| Command | awsr | aws 2.41.2 | Speedup |
|---|---|---|---|
sts get-caller-identity |
6.4 ms | 646 ms | 101× |
dynamodb list-tables |
6.8 ms | 673 ms | 99× |
ec2 describe-regions |
7.8 ms | 846 ms | 109× |
--version |
2.3 ms | 502 ms | 216× |
ec2 help |
4.1 ms | 906 ms | 222× |
The table shows the median wall time of the x86_64-unknown-linux-musl binary of the 0.2.23 release and the official AWS CLI 2.41.2 Linux installer on an Intel Core Ultra 5 225U. hyperfine -N ran each command at least 30 times against a local stub endpoint with static credentials, after checking that both CLIs print the same bytes for the API calls. A real API call adds the same network round trip to both. The speedup is the aws time divided by the awsr time. The machine ran other work during the runs; a second pass gave awsr 5.1 to 6.2 ms for the API calls and aws 679 to 804 ms. ec2 help reads the page cached on the first run, because the groff on this machine (1.24.2) differs from the one the release binary formatted its pages with (see below).
To measure on your machine, give bench/run.sh the two executables. It needs python3 and hyperfine, and writes the hyperfine JSON; bench/chart.py turns it into the table and the chart:
$ bench/run.sh ./awsr "$(command -v aws)" result.json
$ python3 bench/chart.py result.json 2.41.2 "<CPU>" performance.svgawsr embeds the service models and the help inputs uncompressed, in a form it reads in place. A command touches only the parts it uses and parses no JSON at start. With the formatted help pages (36 MB compressed), the binary of the flake package weighs 150 MiB.
The release binaries and the flake package carry every help page formatted by groff at build time (make help-pages): groff 1.23.0 of Ubuntu for the release binaries and the groff of nixpkgs for the flake package. awsr prints these pages when the groff on PATH reports the same version and no GROFF* variable is set. Otherwise it formats the page with the installed groff (or mandoc), as the reference does, and keeps the output in $XDG_CACHE_HOME/awsr/help (or ~/.cache/awsr/help), keyed by the page, the awsr and groff binaries, and the groff and locale environment variables.
$ nix develop
$ make checkawsr-difftest (difftest/) runs awsr and the reference CLI on the same command line against a stub endpoint. The stub answers with responses generated from the operation's output shape. awsr-difftest then compares stdout, stderr, the exit code, the streaming output file, and the recorded requests.
$ make difftest # the cases in difftest/smoke.txt
$ make difftest-full # every operation of every service, 4 seeds, json / text / tableawsr-difftest stores reference runs in target/difftest/refcache, keyed by the reference build and the prepared case, and replays them on later runs. For a run missing from the cache, it forks one reference process that has loaded the CLI.
--refresh-ref-cachereplaces the stored runs.--no-ref-cacheruns the reference for each case.--no-refserverstarts a new reference process for each run.
difftest/exclusions.txt lists the operations you cannot compare against a stub, with the reason for each.
Apache-2.0. The embedded models come from aws/aws-cli (Apache-2.0).
