# LocalStack AWS CLI
This package provides the `awslocalw` command, which is a thin wrapper around the `aws`
command line interface for use with [LocalStack](https://github.com/localstack/localstack).
Commands are suffixed by `w` so they don't conflict with `awslocal`, e.g. `awslocalw`
# Why this fork.
This is to handle this issue:
https://github.com/localstack/awscli-local/issues/84
which undoes this commit for Windows users
https://github.com/localstack/awscli-local/commit/8712c0007294c8f2a80ef47fdea375c8971329ec#diff-b49fad6200a705d348ab2c32761fe0eda06b69e599bd8f305bfa09001660c61bL57
When I say "Windows" I mean cmd.exe, powershell, git-bash but not WSL or WSL2.
## Installation
You can install the `awslocal` command via `pip`:
```console
pip install awscli-local[ver1]
```
If you're on macOS or use ZSH, please use the following command to install `awslocal` via `pip`:
```console
pip install "awscli-local[ver1]"
```
Note that the command above also installs the latest version of the underlying AWS CLI version 1 (`awscli`) package. Use this command if you prefer to manage your own version of `awscli` (e.g., `v1`/`v2`) and install the wrapper script only:
```console
pip install awscli-local
```
**Note:** Automatic installation of AWS CLI version 2 is currently not supported yet (at the time of writing there is no official pypi package for `v2` available), but the `awslocal` technically also works with AWS CLI v2 (see [this section](#Limitations) for more details).
## Usage
The `awslocal` command has the same usage as the `aws` command. For detailed usage, please refer to the manual pages of `aws help`.
## Example
Instead of the following command ...
```console
aws --endpoint-url=http://localhost:4566 kinesis list-streams
```
... you can simply use this:
```console
awslocal kinesis list-streams
```
## Configurations
You can use the following environment variables for configuration:
* `AWS_ENDPOINT_URL`: The endpoint URL to connect to (takes precedence over `USE_SSL`/`LOCALSTACK_HOST` below).
Useful when you have LocalStack bound to a different host (e.g., within docker-compose).
* `LOCALSTACK_HOST` (deprecated): A <hostname>:<port> variable defining where to find LocalStack (default: localhost:4566).
* `USE_SSL` (deprecated): Whether to use SSL when connecting to LocalStack (default: False).
## Completion
`awscli` provides a neat command completion feature which is compatible with most modern shells which can also be used with `awslocal`.
### Usage instructions
The command completion will automatically suggest commands and parameters when using the completion key (which is typically the _Tab_ key):
```sh
$ awslocal dynamodb d<TAB>
delete-backup describe-global-table
delete-item describe-global-table-settings
delete-table describe-limits
describe-backup describe-table
describe-continuous-backups describe-table-replica-auto-scaling
describe-contributor-insights describe-time-to-live
describe-endpoints
```
### Configuration
- Follow the official guide on setting up the command completion for the `aws` CLI: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-completion.html
- While enabling the command completion for your shell, **make sure to register the completion for `awslocal` as well**.
For example, if you are using `bash`, you would add the following commands to your `~/.bashrc`:
```sh
complete -C '/usr/local/bin/aws_completer' aws
complete -C '/usr/local/bin/aws_completer' awslocal
```
- Follow the instructions for the shell you are using. For some shells you might need to register a different command or enable certain compatibility plugins (like `zsh`).
## Limitations
* Please note that there is a known limitation for using the `cloudformation package ...` command with the AWS CLI v2. Currently it is not possible to specify the S3 endpoint URL, and this issue is [not yet resolved](https://github.com/aws/aws-cli/pull/3309) on AWS side. The problem is that the AWS CLI v2 is [not available as a package on pypi.org](https://github.com/aws/aws-cli/issues/4947), but is instead shipped as a binary package that cannot be easily patched from `awslocal`. To work around this issue, you have 2 options:
- Downgrade to the v1 AWS CLI (this is the recommended approach)
- There is an inofficial way to install AWS CLI v2 from sources. We do not recommend this, but it is technically possible. Also, you should install these libraries in a Python virtualenv, to avoid version clashes with other libraries on your system:
```sh
virtualenv .venv
. .venv/bin/activate
pip install https://github.com/boto/botocore/archive/v2.zip https://github.com/aws/aws-cli/archive/v2.zip
```
## Change Log
* v0.22.0: Use fallback for endpoint detection. Should prevent most cases of `Unable to find LocalStack endpoint for service ...`
* v0.21.1: Introducing semantic versioning and list of services without endpoints
* v0.21: Use placeholder credentials and region only if Boto cannot not find them, fix output streaming for logs tail call
* v0.20: Small fixes for Python 2.x backward compatibility
* v0.19: Patch botocore to skip adding `data-` host prefixes to endpoint URLs
* v0.18: Pass `SYSTEMROOT` env variable to fix "_Py_HashRandomization_Init" error on Windows
* v0.17: Remove obsolete/erroneous FORCE_V2 flag
* v0.16: Minor fix reading addressing_style in profile config
* v0.15: Fix lookup of v1/v2 AWS CLI version, apply --s3-endpoint-url only for v1
* v0.14: Quote file name for windows to allow folder names with spaces
* v0.13: Fix extra requires for newer pip versions
* v0.12: Support v1 and v2 of underlying `awscli` installation
* v0.9: Add `--s3-endpoint-url` by default to fix "cloudformation package" command
* v0.9: Support for `DEFAULT_REGION` environment variable
* v0.8: Switch to using edge port for all service endpoints by default
* v0.7: Apply runtime patch to aws-cli to enable `--s3-endpoint-url` CloudFormation parameter
* v0.6: Start `aws` CLI command in-memory instead of calling external process
* v0.5: Support piping binary files to stdout; add .bat file for Windows
* v0.4: Minor fix for Python 3 compatibility
* v0.3: Add support for additional service endpoints
* v0.2: Enable SSL connections; refactor code
* v0.1: Initial release
## Alternative
This package can be replaced by a single bash alias, except for `cloudformation package ...` as this command requires an additional `--s3-endpoint-url` parameter:
```console
alias awslocal="AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=${DEFAULT_REGION:-$AWS_DEFAULT_REGION} aws --endpoint-url=http://${LOCALSTACK_HOST:-localhost}:4566"
```
## License
This software library is released under the Apache License, Version 2.0 (see `LICENSE`).
[pypi-version]: https://img.shields.io/pypi/v/awscli-local.svg
[pypi]: https://pypi.org/project/awscli-local/
Raw data
{
"_id": null,
"home_page": null,
"name": "awscli-local-win",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "aws, localstack, cli, windows",
"author": "LocalStack Team",
"author_email": "Matthew Martin <matthewdeanmartin@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3f/da/f4a4ad84f5e9d03545dd7338eed78232c4de085ce98c5ac4a2afc40af347/awscli_local_win-0.26.0.tar.gz",
"platform": null,
"description": "# LocalStack AWS CLI\n\nThis package provides the `awslocalw` command, which is a thin wrapper around the `aws`\ncommand line interface for use with [LocalStack](https://github.com/localstack/localstack).\n\nCommands are suffixed by `w` so they don't conflict with `awslocal`, e.g. `awslocalw` \n\n# Why this fork.\nThis is to handle this issue:\n\nhttps://github.com/localstack/awscli-local/issues/84\n\nwhich undoes this commit for Windows users\n\nhttps://github.com/localstack/awscli-local/commit/8712c0007294c8f2a80ef47fdea375c8971329ec#diff-b49fad6200a705d348ab2c32761fe0eda06b69e599bd8f305bfa09001660c61bL57\n\nWhen I say \"Windows\" I mean cmd.exe, powershell, git-bash but not WSL or WSL2.\n\n## Installation\n\nYou can install the `awslocal` command via `pip`:\n\n```console\npip install awscli-local[ver1]\n```\n\nIf you're on macOS or use ZSH, please use the following command to install `awslocal` via `pip`:\n```console\npip install \"awscli-local[ver1]\"\n```\n\nNote that the command above also installs the latest version of the underlying AWS CLI version 1 (`awscli`) package. Use this command if you prefer to manage your own version of `awscli` (e.g., `v1`/`v2`) and install the wrapper script only:\n```console\npip install awscli-local\n```\n\n**Note:** Automatic installation of AWS CLI version 2 is currently not supported yet (at the time of writing there is no official pypi package for `v2` available), but the `awslocal` technically also works with AWS CLI v2 (see [this section](#Limitations) for more details).\n\n## Usage\n\nThe `awslocal` command has the same usage as the `aws` command. For detailed usage, please refer to the manual pages of `aws help`.\n\n## Example\n\nInstead of the following command ...\n\n```console\naws --endpoint-url=http://localhost:4566 kinesis list-streams\n```\n\n... you can simply use this:\n\n```console\nawslocal kinesis list-streams\n```\n\n## Configurations\n\nYou can use the following environment variables for configuration:\n\n* `AWS_ENDPOINT_URL`: The endpoint URL to connect to (takes precedence over `USE_SSL`/`LOCALSTACK_HOST` below).\n Useful when you have LocalStack bound to a different host (e.g., within docker-compose).\n* `LOCALSTACK_HOST` (deprecated): A <hostname>:<port> variable defining where to find LocalStack (default: localhost:4566).\n* `USE_SSL` (deprecated): Whether to use SSL when connecting to LocalStack (default: False).\n\n## Completion\n\n`awscli` provides a neat command completion feature which is compatible with most modern shells which can also be used with `awslocal`.\n\n### Usage instructions\n\nThe command completion will automatically suggest commands and parameters when using the completion key (which is typically the _Tab_ key):\n\n```sh\n$ awslocal dynamodb d<TAB>\ndelete-backup describe-global-table\ndelete-item describe-global-table-settings\ndelete-table describe-limits\ndescribe-backup describe-table\ndescribe-continuous-backups describe-table-replica-auto-scaling\ndescribe-contributor-insights describe-time-to-live\ndescribe-endpoints\n```\n\n### Configuration\n\n- Follow the official guide on setting up the command completion for the `aws` CLI: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-completion.html\n- While enabling the command completion for your shell, **make sure to register the completion for `awslocal` as well**.\n\n For example, if you are using `bash`, you would add the following commands to your `~/.bashrc`:\n ```sh\n complete -C '/usr/local/bin/aws_completer' aws\n complete -C '/usr/local/bin/aws_completer' awslocal\n ```\n- Follow the instructions for the shell you are using. For some shells you might need to register a different command or enable certain compatibility plugins (like `zsh`).\n\n## Limitations\n\n* Please note that there is a known limitation for using the `cloudformation package ...` command with the AWS CLI v2. Currently it is not possible to specify the S3 endpoint URL, and this issue is [not yet resolved](https://github.com/aws/aws-cli/pull/3309) on AWS side. The problem is that the AWS CLI v2 is [not available as a package on pypi.org](https://github.com/aws/aws-cli/issues/4947), but is instead shipped as a binary package that cannot be easily patched from `awslocal`. To work around this issue, you have 2 options:\n\n - Downgrade to the v1 AWS CLI (this is the recommended approach)\n - There is an inofficial way to install AWS CLI v2 from sources. We do not recommend this, but it is technically possible. Also, you should install these libraries in a Python virtualenv, to avoid version clashes with other libraries on your system:\n```sh\nvirtualenv .venv\n. .venv/bin/activate\npip install https://github.com/boto/botocore/archive/v2.zip https://github.com/aws/aws-cli/archive/v2.zip\n```\n\n## Change Log\n\n* v0.22.0: Use fallback for endpoint detection. Should prevent most cases of `Unable to find LocalStack endpoint for service ...`\n* v0.21.1: Introducing semantic versioning and list of services without endpoints\n* v0.21: Use placeholder credentials and region only if Boto cannot not find them, fix output streaming for logs tail call\n* v0.20: Small fixes for Python 2.x backward compatibility\n* v0.19: Patch botocore to skip adding `data-` host prefixes to endpoint URLs\n* v0.18: Pass `SYSTEMROOT` env variable to fix \"_Py_HashRandomization_Init\" error on Windows\n* v0.17: Remove obsolete/erroneous FORCE_V2 flag\n* v0.16: Minor fix reading addressing_style in profile config\n* v0.15: Fix lookup of v1/v2 AWS CLI version, apply --s3-endpoint-url only for v1\n* v0.14: Quote file name for windows to allow folder names with spaces\n* v0.13: Fix extra requires for newer pip versions\n* v0.12: Support v1 and v2 of underlying `awscli` installation\n* v0.9: Add `--s3-endpoint-url` by default to fix \"cloudformation package\" command\n* v0.9: Support for `DEFAULT_REGION` environment variable\n* v0.8: Switch to using edge port for all service endpoints by default\n* v0.7: Apply runtime patch to aws-cli to enable `--s3-endpoint-url` CloudFormation parameter\n* v0.6: Start `aws` CLI command in-memory instead of calling external process\n* v0.5: Support piping binary files to stdout; add .bat file for Windows\n* v0.4: Minor fix for Python 3 compatibility\n* v0.3: Add support for additional service endpoints\n* v0.2: Enable SSL connections; refactor code\n* v0.1: Initial release\n\n## Alternative\n\nThis package can be replaced by a single bash alias, except for `cloudformation package ...` as this command requires an additional `--s3-endpoint-url` parameter:\n```console\nalias awslocal=\"AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=${DEFAULT_REGION:-$AWS_DEFAULT_REGION} aws --endpoint-url=http://${LOCALSTACK_HOST:-localhost}:4566\"\n```\n\n## License\n\nThis software library is released under the Apache License, Version 2.0 (see `LICENSE`).\n\n[pypi-version]: https://img.shields.io/pypi/v/awscli-local.svg\n[pypi]: https://pypi.org/project/awscli-local/\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Thin wrapper around the 'aws' command line interface for use with LocalStack *for Windows*.",
"version": "0.26.0",
"project_urls": {
"homepage": "https://github.com/matthewdeanmartin/awscli-local"
},
"split_keywords": [
"aws",
" localstack",
" cli",
" windows"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f66df880ad65009e2a51872241f8b82f82b15ea2561c5956db591ac27bfe10ea",
"md5": "38d00ae8ccaafb1d48b39b72c9fc4876",
"sha256": "3e007d70ca2b1c1d103000935e21388db5823b3f6d636a237ff2a3a80ecb06b6"
},
"downloads": -1,
"filename": "awscli_local_win-0.26.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "38d00ae8ccaafb1d48b39b72c9fc4876",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12897,
"upload_time": "2024-10-24T18:28:00",
"upload_time_iso_8601": "2024-10-24T18:28:00.418818Z",
"url": "https://files.pythonhosted.org/packages/f6/6d/f880ad65009e2a51872241f8b82f82b15ea2561c5956db591ac27bfe10ea/awscli_local_win-0.26.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3fdaf4a4ad84f5e9d03545dd7338eed78232c4de085ce98c5ac4a2afc40af347",
"md5": "ff75631e0e76209341955ce91b0a98a8",
"sha256": "58106c0a1a5ba9d7804d92a465c9ec165d57dcec2f8b4b10c509997c0c2d9203"
},
"downloads": -1,
"filename": "awscli_local_win-0.26.0.tar.gz",
"has_sig": false,
"md5_digest": "ff75631e0e76209341955ce91b0a98a8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12462,
"upload_time": "2024-10-24T18:28:01",
"upload_time_iso_8601": "2024-10-24T18:28:01.717508Z",
"url": "https://files.pythonhosted.org/packages/3f/da/f4a4ad84f5e9d03545dd7338eed78232c4de085ce98c5ac4a2afc40af347/awscli_local_win-0.26.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-24 18:28:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "matthewdeanmartin",
"github_project": "awscli-local",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "awscli-local-win"
}
JSON
