docs(aws): migrate /aws/customization and remaining /aws/services pages to use lstk (#862)

Author: peter-smith-phd

src/content/docs/aws/customization/advanced/arm64-support.md

@@ -12,7 +12,7 @@ This manifest contains links to a Linux AMD64 as well as a Linux ARM64 image.
 
 ## Pulling the LocalStack image
 
-With the multi-arch Docker manifest, your Docker client (and therefore the [LocalStack CLI](/aws/getting-started/installation/#localstack-cli)) now automatically selects the image according to your platform:
+With the multi-arch Docker manifest, your Docker client (and therefore [`lstk`](/aws/developer-tools/running-localstack/lstk)) now automatically selects the image according to your platform:
 
 ```bash
 docker pull localstack/localstack

src/content/docs/aws/customization/advanced/cross-account-access.md

@@ -13,14 +13,17 @@ This document provides information to help design such setups.
 
 :::note
 Cross-account support in LocalStack is being actively developed.
-Please report any issues on our [GitHub Discussions board](https://github.com/orgs/localstack/discussions/categories/bugs).
+Please report any issues to [LocalStack Support](/aws/help-support/get-help).
 :::
 
 Cross-account/cross-region access happens when a client attempts to access a resource in another account or region than what it is configured with:
 
+The examples below select the account with the `--account` flag of `lstk aws`.
+You can also set the account ID through the `AWS_ACCESS_KEY_ID` environment variable, for example `AWS_ACCESS_KEY_ID=111111111111 lstk aws ...`.
+
 ```bash
 # Create a queue in one account and region
-AWS_ACCESS_KEY_ID=111111111111 awslocal sqs create-queue \
+lstk aws --account 111111111111 sqs create-queue \
     --queue-name my-queue \
     --region ap-south-1
 ```
@@ -33,14 +36,14 @@ AWS_ACCESS_KEY_ID=111111111111 awslocal sqs create-queue \
 
 ```bash
 # Set some attributes
-AWS_ACCESS_KEY_ID=111111111111 awslocal sqs set-queue-attributes \
+lstk aws --account 111111111111 sqs set-queue-attributes \
     --attributes VisibilityTimeout=60 \
     --queue-url http://sqs.ap-south-1.localhost.localstack.cloud:443/111111111111/my-queue \
     --region ap-south-1
 
 # Retrieve the queue attribute from another account and region
 # The required information for LocalStack to locate the queue is available in the queue URL
-AWS_ACCESS_KEY_ID=222222222222 awslocal sqs get-queue-attributes \
+lstk aws --account 222222222222 sqs get-queue-attributes \
     --attribute-names VisibilityTimeout \
     --region eu-central-1 \
     --queue-url http://sqs.ap-south-1.localhost.localstack.cloud:443/111111111111/my-queue

src/content/docs/aws/customization/advanced/filesystem.mdx

@@ -100,12 +100,17 @@ In this case, the effective layout would be something like:
         - zipfile.4986fb95
 </FileTree>
 
-### Using the CLI
+### Using lstk
 
-When using the CLI to start LocalStack, the volume directory can be configured via the `LOCALSTACK_VOLUME_DIR`.
-It should point to a directory on the host which is then automatically mounted into `/var/lib/localstack`.
-The defaults are:
+When using [`lstk`](/aws/developer-tools/running-localstack/lstk) to start LocalStack, the volume directory is configured with the `volume` field on a container block.
+It should point to a directory on the host which is then automatically mounted into `/var/lib/localstack`:
 
-- Mac: `~/Library/Caches/localstack/volume`
-- Linux: `~/.cache/localstack/volume`
-- Windows: `%LOCALAPPDATA%\cache\localstack\volume`
+```toml
+# .lstk/config.toml
+[[containers]]
+type   = "aws"
+volume = "./volume"
+```
+
+If `volume` is not set, `lstk` defaults to `<os-cache>/lstk/volume/<container-name>`.
+Run [`lstk volume path`](/aws/developer-tools/running-localstack/lstk#volume) to print the resolved directory.

src/content/docs/aws/customization/advanced/initialization-hooks.mdx

@@ -123,15 +123,16 @@ If you have more complex states, [Cloud Pods](/aws/developer-tools/snapshots/clo
 To execute aws cli commands when LocalStack becomes ready,
 simply create a script `init-aws.sh` and mount it into `/etc/localstack/init/ready.d/`.
 Make sure the script is executable: run `chmod +x init-aws.sh` on the file first.
-You can use anything available inside the container, including `awslocal`:
+You can use anything available inside the container, and can install new software:
 
 ```bash
 #!/bin/bash
 
-export AWS_ACCESS_KEY_ID=000000000000 AWS_SECRET_ACCESS_KEY=000000000000
+npm install -g @localstack/lstk
+lstk setup aws
 
-awslocal s3 mb s3://my-bucket
-awslocal sqs create-queue --queue-name my-queue
+lstk aws s3 mb s3://my-bucket
+lstk aws sqs create-queue --queue-name my-queue
 ```
 
 Start Localstack:
@@ -153,11 +154,22 @@ services:
       - "/var/run/docker.sock:/var/run/docker.sock"
 ```
 </TabItem>
-<TabItem value="CLI" label="CLI">
-```bash
-# DOCKER_FLAGS are additional parameters to the `docker run` command of localstack start
+<TabItem value="lstk" label="lstk">
+Declare the bind mount and the `DEBUG` profile in your config file, then start LocalStack:
+
+```toml
+# .lstk/config.toml
+[[containers]]
+type    = "aws"
+env     = ["debug"]
+volumes = ["/path/to/init-aws.sh:/etc/localstack/init/ready.d/init-aws.sh"]
+
+[env.debug]
+DEBUG = "1"
+```
 
-DOCKER_FLAGS='-v /path/to/init-aws.sh:/etc/localstack/init/ready.d/init-aws.sh' localstack start
+```bash
+lstk start
 ```
 </TabItem>
 </Tabs>
@@ -172,8 +184,8 @@ and for more details on running init hooks in development mode, you can check ou
 
 Start LocalStack with **`EXTENSION_AUTO_INSTALL="localstack-extension-terraform-init"`**.
 Mount a **`main.tf`** file into **`/etc/localstack/init/ready.d`**
-When LocalStack starts up, it will install the extension, which in turn installs Terraform and [`tflocal`](https://github.com/localstack/terraform-local) into the container.
-If one of the init stage directories contain a `main.tf` file, the extension will run `tflocal init` and `tflocal apply` on that directory.
+When LocalStack starts up, it will install the extension, which in turn installs Terraform into the container.
+If one of the init stage directories contain a `main.tf` file, the extension will run `terraform init` and `terraform apply` on that directory.
 
 ```terraform
 # main.tf
@@ -210,19 +222,28 @@ services:
       - "/var/run/docker.sock:/var/run/docker.sock"
 ```
 </TabItem>
-<TabItem value="LocalStack CLI" label="LocalStack CLI">
+<TabItem value="lstk" label="lstk">
+```toml
+# .lstk/config.toml
+[[containers]]
+type    = "aws"
+env     = ["terraform-init"]
+volumes = ["./main.tf:/etc/localstack/init/ready.d/main.tf"]
+
+[env.terraform-init]
+EXTENSION_AUTO_INSTALL = "localstack-extension-terraform-init"
+```
+
 ```bash
-localstack start \
-  -e EXTENSION_AUTO_INSTALL="localstack-extension-terraform-init" \
-  -v ./main.tf:/etc/localstack/init/ready.d/main.tf
+lstk start
 ```
 </TabItem>
 </Tabs>
 
 You can wait for LocalStack to complete the startup process, and then print the created S3 bucket:
 
 ```bash
-localstack wait && awslocal s3 ls
+lstk aws s3 ls
 ```
 
 The logs should show something like:

src/content/docs/aws/customization/advanced/multi-account-setups.md

@@ -8,7 +8,7 @@ sidebar:
 
 :::note
 Please note that multi-accounts may not work for use-cases that have cross-account and cross-service access.
-Please open a [GitHub Discussion](https://github.com/orgs/localstack/discussions/new/choose) to request and upvote for support for specific use-cases.
+Please contact [LocalStack Support](/aws/help-support/get-help) to request support for specific use-cases.
 :::
 
 LocalStack ships with multi-account support which allows namespacing based on AWS account ID.
@@ -20,14 +20,13 @@ The Access Key ID field can be configured in the AWS CLI in multiple ways: pleas
 
 ## Examples
 
-In following examples, we configure the AWS CLI account ID via environment variable.
+In the following examples, we select the account ID with the `--account` flag of `lstk aws`.
 
 ```bash
-AWS_ACCESS_KEY_ID=000000000001 awslocal ec2 create-key-pair --key-name green-hospital
+lstk aws --account 000000000001 ec2 create-key-pair --key-name green-hospital
+lstk aws --account 000000000002 ec2 create-key-pair --key-name red-medicine
 
-AWS_ACCESS_KEY_ID=000000000002 awslocal ec2 create-key-pair --key-name red-medicine
-
-AWS_ACCESS_KEY_ID=000000000001 awslocal ec2 describe-key-pairs
+lstk aws --account 000000000001 ec2 describe-key-pairs
 {
     "KeyPairs": [
         {
@@ -37,7 +36,7 @@ AWS_ACCESS_KEY_ID=000000000001 awslocal ec2 describe-key-pairs
     ]
 }
 
-AWS_ACCESS_KEY_ID=000000000002 awslocal ec2 describe-key-pairs
+lstk aws --account 000000000002 ec2 describe-key-pairs
 {
     "KeyPairs": [
         {
@@ -48,11 +47,17 @@ AWS_ACCESS_KEY_ID=000000000002 awslocal ec2 describe-key-pairs
 }
 ```
 
+Alternatively, you can set the account ID through the `AWS_ACCESS_KEY_ID` environment variable:
+
+```bash
+AWS_ACCESS_KEY_ID=000000000001 lstk aws ec2 describe-key-pairs
+```
+
 If no explicit Account ID is set, LocalStack falls back to default.
 In this example, no resources are returned.
 
 ```bash
-awslocal ec2 describe-key-pairs
+lstk aws ec2 describe-key-pairs
 {
     "KeyPairs": []
 }

src/content/docs/aws/customization/advanced/usage-tracking.md

@@ -96,7 +96,7 @@ Here is an example of a CLI invocation event:
     "client_time": "2022-08-30 14:46:54.116457"
   },
   "payload": {
-    "cmd": "localstack config validate",
+    "cmd": "lstk start",
     "params": [
       "file"
     ]

src/content/docs/aws/customization/configuration-options.md

@@ -6,17 +6,33 @@ template: doc
 
 LocalStack exposes various configuration options to control its behaviour.
 
-These options can be passed to LocalStack as environment variables like so:
+With `lstk`, these options can be passed as `LOCALSTACK_`-prefixed environment variables when starting the container:
 
 ```bash
-DEBUG=1 localstack start
+LOCALSTACK_DEBUG=1 lstk start
 ```
 
+Alternatively, set them as named environment profiles in your config file and reference them from the container block:
+
+```toml
+# .lstk/config.toml
+[[containers]]
+type = "aws"
+env  = ["debug"]
+
+[env.debug]
+DEBUG = "1"
+```
+
+```bash
+lstk start
+```
+
+See [Passing environment variables to the container](/aws/developer-tools/running-localstack/lstk#passing-environment-variables-to-the-container) for details.
+
 To facilitate interoperability, configuration variables can be prefixed with `LOCALSTACK_` in docker.
 For instance, setting `LOCALSTACK_PERSISTENCE=1` is equivalent to `PERSISTENCE=1`.
 
-You can also use [Profiles](#profiles).
-
 Configurations marked as **Deprecated** will be removed in the next major version.
 You can find previously removed configuration variables under [Legacy](#legacy).
 
@@ -44,20 +60,16 @@ Options that affect the core LocalStack system.
 
 ## CLI
 
-These options are applicable when using the CLI to start LocalStack.
-
-| Variable | Example Values | Description |
-| - | - | - |
-| `LOCALSTACK_VOLUME_DIR` | `~/.cache/localstack/volume` (on Linux) | The location on the host of the LocalStack volume directory mount. See [Filesystem Layout](/aws/customization/advanced/filesystem#using-the-cli) |
-| `CONFIG_PROFILE` | | The configuration profile to load. See [Profiles](#profiles) |
-| `CONFIG_DIR` | `~/.localstack` | The path where LocalStack can find configuration profiles and other CLI-specific configuration |
+`lstk` is configured through its config file rather than through environment variables.
+See [Configuration](/aws/developer-tools/running-localstack/lstk#configuration) on the `lstk` page for the config file search order, the field reference, and how to define named environment profiles.
 
 ## Docker
 
 Options to configure how LocalStack interacts with Docker.
 
 | Variable | Example Values | Description |
 | - | - | - |
+| `LOCALSTACK_VOLUME_DIR` | `~/.cache/localstack/volume` (on Linux) | The location on the host of the LocalStack volume directory mount. See [Filesystem Layout](/aws/customization/advanced/filesystem) |
 | `DOCKER_FLAGS` | | Allows to pass custom flags (e.g., volume mounts) to "docker run" when running LocalStack in Docker. |
 | `DOCKER_SOCK` | `/var/run/docker.sock` | Path to local Docker UNIX domain socket |
 | `DOCKER_BRIDGE_IP` | `172.17.0.1` | IP of the docker bridge used to enable access between containers |
@@ -540,51 +552,3 @@ These configurations have already been removed and **won't have any effect** on
 | `TMPDIR`| 2.0.0 | `/tmp` (default) |  Temporary folder on the host running the CLI and inside the LocalStack container .|
 | `USE_LIGHT_IMAGE` | 2.0.0 | `1` (default) | Whether to use the light-weight Docker image. Overwritten by `IMAGE_NAME`.|
 | `PORT_WEB_UI` | 0.12.8 | `8080` (default) | Port for the legacy Web UI. Replaced by our [Web Application](https://app.localstack.cloud) |
-
-## Profiles
-
-LocalStack supports configuration profiles which are stored in the `~/.localstack` config directory.
-If the directory does not exist, create it manually.
-A configuration profile is a set of environment variables stored in an `.env` file in the LocalStack config directory.
-
-Here is an example of what configuration profiles might look like:
-
-```bash
-tree ~/.localstack
-/home/username/.localstack
-├── default.env
-├── dev.env
-└── pro.env
-```
-
-Here is an example of what a specific environment profile looks like
-
-```bash
-cat ~/.localstack/pro-debug.env
-LOCALSTACK_AUTH_TOKEN=XXXXX
-DEBUG=1
-DEVELOP=1
-```
-
-You can load a profile by either setting the `env` variable `CONFIG_PROFILE=<profile>` or the `--profile=<profile>` CLI flag when using the CLI.
-Let's take an example to load the `dev.env` profile file if it exists:
-
-```bash
-python -m localstack.cli.main --profile=dev start
-```
-
-If no profile is specified, the `default.env` profile will be loaded.
-While explicitly specified, the environment variables will always overwrite the profile.
-
-To display the config environment variables, you can use the following command:
-
-```bash
-python -m localstack.cli.main --profile=dev config show
-```
-
-:::note
-The `CONFIG_PROFILE` is a CLI feature and cannot be used with a Docker/Docker Compose setup.
-You can look at [alternative means of setting environment variables](https://docs.docker.com/compose/environment-variables/set-environment-variables/) for your Docker Compose setups.
-
-For Docker setups, we recommend passing the environment variables directly to the `docker run` command.
-:::

src/content/docs/aws/customization/integrations/app-frameworks/aspire.md

@@ -12,7 +12,7 @@ sidebar:
 
 With Aspire, developers can orchestrate cloud-native applications locally using the same AWS resources they deploy in production. By combining Aspire with LocalStack, teams can emulate their full cloud environment—including Lambda, SQS, S3, and DynamoDB—with minimal configuration and no AWS costs.
 
-LocalStack integrates with Aspire through the [`LocalStack.Aspire.Hosting`](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack) package, enabling seamless local development and testing of AWS-powered applications within the Aspire orchestration framework. This package extends the official [AWS integrations for .NET Aspire](https://github.com/aws/customization/integrations-on-dotnet-aspire-for-aws) to provide LocalStack-specific functionality.
+LocalStack integrates with Aspire through the [`LocalStack.Aspire.Hosting`](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack) package, enabling seamless local development and testing of AWS-powered applications within the Aspire orchestration framework. This package extends the official [AWS integrations for .NET Aspire](https://github.com/aws/integrations-on-dotnet-aspire-for-aws) to provide LocalStack-specific functionality.
 
 ## Getting started
 
@@ -168,7 +168,7 @@ An event registration system showcasing distributed tracing and observability pa
 - [Aspire Documentation](https://aspire.dev/)
 - [LocalStack.Aspire.Hosting on GitHub](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack)
 - [LocalStack.Client on GitHub](https://github.com/localstack-dotnet/localstack-dotnet-client)
-- [AWS Aspire Integration](https://github.com/aws/customization/integrations-on-dotnet-aspire-for-aws)
+- [AWS Aspire Integration](https://github.com/aws/integrations-on-dotnet-aspire-for-aws)
 - [AWS SDK for .NET Documentation](https://docs.aws.amazon.com/sdk-for-net/)
 - [LocalStack Serverless .NET Demo](https://github.com/localstack-dotnet/localstack-serverless-dotnet-demo)
 - [OpenTelemetry with Aspire and LocalStack Demo](https://github.com/Blind-Striker/dotnet-otel-aspire-localstack-demo)

src/content/docs/aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster.md

@@ -22,7 +22,7 @@ docker-compose up -d
 2. Create the Lambda function:
 
 ```bash showshowLineNumbers
-awslocal lambda create-function \
+lstk aws lambda create-function \
     --function-name fun1 \
     --handler lambda.handler \
     --runtime python3.8 \
@@ -54,7 +54,7 @@ awslocal lambda create-function \
 3. Create an example secret:
 
 ```bash showshowLineNumbers
-awslocal secretsmanager create-secret --name localstack
+lstk aws secretsmanager create-secret --name localstack
 {
     "ARN": "arn:aws:secretsmanager:us-east-1:000000000000:secret:localstack-TDIuI",
     "Name": "localstack",
@@ -72,7 +72,7 @@ Created topic t1.
 5. Create the event source mapping to your local kafka cluster:
 
 ```bash showshowLineNumbers
-awslocal lambda create-event-source-mapping \
+lstk aws lambda create-event-source-mapping \
     --topics t1 \
     --source-access-configuration Type=SASL_SCRAM_512_AUTH,URI=arn:aws:secretsmanager:us-east-1:000000000000:secret:localstack-TDIuI \
     --function-name arn:aws:lambda:us-east-1:000000000000:function:fun1 \

src/content/docs/aws/customization/integrations/extensions/developing-extensions.mdx

@@ -150,6 +150,11 @@ reference points to the plugin class.
 
 ## Using the extensions developer CLI
 
+:::note
+The new CLI experience, `lstk`, does not support LocalStack Extensions. There is no `lstk extensions` command suite.
+Continue using the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/) for the commands in this section.
+:::
+
 The extensions CLI has a set of developer commands that allow you to create new extensions, and toggle local dev mode for extensions.
 Extensions that are toggled for developer mode will be mounted into the localstack container so you don't need to re-install them every time you change something.