Skip to content

About

A fast, output-compatible Rust reimplementation of the AWS CLI v2

Topics

Resources

Stars

18 stars

Watchers

0 watching

Forks

Repository files navigation

awsr

A fast, output-compatible Rust reimplementation of the AWS CLI v2

Latest release CI License: Apache-2.0 Rust 1.94 GitHub stars

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-identity

Median wall time of awsr and aws 2.41.2 for five commands

The 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, --query expressions, and --output formats give the same bytes they give with aws. Differential testing runs both CLIs on the operations of all services and compares what they print.
  • Its own name. What awsr says about itself names awsr: --version prints awsr/<version> (aws-cli/<reference version> compatible) <system>/<release> <machine>, and the usage lines, the awsr: [ERROR]: prefix of error messages, and the command lines of the help pages name awsr. The text of messages and help pages is the reference's.
  • All services. awsr embeds 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 as awsr <service> <operation>.

awsr is not an official AWS product.

Install

Prebuilt binaries

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

$ nix profile install github:conao3/rust-awscli

Cargo

$ cargo install awsr

The 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.

Usage

Replace aws with awsr:

$ awsr sts get-caller-identity
$ awsr dynamodb list-tables --output table
$ awsr ec2 describe-instances --query 'Reservations[].Instances[].InstanceId' --output text

awsr reads the same ~/.aws/config, ~/.aws/credentials, SSO token cache, and environment variables as the AWS CLI.

Shell completion

bash (~/.bashrc):

if command -v aws_completer > /dev/null; then
    complete -C aws_completer awsr
fi

zsh (~/.zshrc):

autoload -Uz bashcompinit && bashcompinit
if command -v aws_completer > /dev/null; then
    complete -C aws_completer awsr
fi

fish (~/.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

Performance

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.svg

awsr 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.

Development

$ nix develop
$ make check

Differential testing

awsr-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 / table

awsr-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-cache replaces the stored runs.
  • --no-ref-cache runs the reference for each case.
  • --no-refserver starts a new reference process for each run.

difftest/exclusions.txt lists the operations you cannot compare against a stub, with the reason for each.

License

Apache-2.0. The embedded models come from aws/aws-cli (Apache-2.0).

About

A fast, output-compatible Rust reimplementation of the AWS CLI v2

Topics

Resources

Stars

18 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages