DOC-386: Split lstk CLI docs into a multi-page structure

astro.config.mjs

@@ -484,7 +484,45 @@ export default defineConfig({
                     },
                     {
                       label: 'lstk CLI',
-                      slug: 'aws/developer-tools/running-localstack/lstk',
+                      collapsed: true,
+                      items: [
+                        {
+                          label: 'Overview',
+                          slug: 'aws/developer-tools/running-localstack/lstk',
+                        },
+                        {
+                          label: 'Authentication',
+                          slug: 'aws/developer-tools/running-localstack/lstk/authentication',
+                        },
+                        {
+                          label: 'Configuration',
+                          slug: 'aws/developer-tools/running-localstack/lstk/configuration',
+                        },
+                        {
+                          label: 'Lifecycle Commands',
+                          slug: 'aws/developer-tools/running-localstack/lstk/lifecycle-commands',
+                        },
+                        {
+                          label: 'AWS & IaC Commands',
+                          slug: 'aws/developer-tools/running-localstack/lstk/aws-and-iac-commands',
+                        },
+                        {
+                          label: 'Snapshots',
+                          slug: 'aws/developer-tools/running-localstack/lstk/snapshots',
+                        },
+                        {
+                          label: 'Automation & CI',
+                          slug: 'aws/developer-tools/running-localstack/lstk/automation',
+                        },
+                        {
+                          label: 'Setup & Maintenance',
+                          slug: 'aws/developer-tools/running-localstack/lstk/setup-and-maintenance',
+                        },
+                        {
+                          label: 'FAQ & Troubleshooting',
+                          slug: 'aws/developer-tools/running-localstack/lstk/faq-and-troubleshooting',
+                        },
+                      ],
                     },
                     {
                       label: 'LocalStack MCP Server',

public/_redirects

@@ -379,7 +379,7 @@
 /user-guide/aws/stepfunctions/ /aws/services/stepfunctions/ 301
 /references/coverage/coverage_elasticache/ /aws/services/elasticache/ 301
 /applications/mnist-handwritten-digit-recognition-model-running-on-a-local-sagemaker-endpoint/ https://github.com/localstack-samples/sample-mnist-digit-recognition-sagemaker 301
-/user-guide/state-management/pods-cli/ /aws/developer-tools/running-localstack/lstk/#snapshot 301
+/user-guide/state-management/pods-cli/ /aws/developer-tools/running-localstack/lstk/snapshots/#snapshot 301
 /user-guide/aws/dynamodbstreams/ /aws/services/dynamodbstreams/ 301
 /references/api-key/ /aws/getting-started/auth-token/#how-do-i-activate-older-versions-of-localstack-before-v30/ 301
 /references/coverage/coverage_eks/ /aws/services/eks/ 301
@@ -779,7 +779,7 @@
 /user-guide/aws/stepfunctions /aws/services/stepfunctions/ 301
 /references/coverage/coverage_elasticache /aws/services/elasticache/ 301
 /applications/mnist-handwritten-digit-recognition-model-running-on-a-local-sagemaker-endpoint https://github.com/localstack-samples/sample-mnist-digit-recognition-sagemaker 301
-/user-guide/state-management/pods-cli /aws/developer-tools/running-localstack/lstk/#snapshot 301
+/user-guide/state-management/pods-cli /aws/developer-tools/running-localstack/lstk/snapshots/#snapshot 301
 /user-guide/aws/dynamodbstreams /aws/services/dynamodbstreams/ 301
 /references/api-key /aws/getting-started/auth-token/#how-do-i-activate-older-versions-of-localstack-before-v30/ 301
 /references/coverage/coverage_eks /aws/services/eks/ 301
@@ -861,15 +861,15 @@
 /aws/integrations/aws-native-tools /aws/connecting/ 301
 /aws/integrations/infrastructure-as-code/ /aws/connecting/infrastructure-as-code/ 301
 /aws/integrations/infrastructure-as-code /aws/connecting/infrastructure-as-code/ 301
-/aws/capabilities/state-management/cli-commands /aws/developer-tools/running-localstack/lstk/#snapshot 301
-/aws/capabilities/state-management/cli-commands/ /aws/developer-tools/running-localstack/lstk/#snapshot 301
+/aws/capabilities/state-management/cli-commands /aws/developer-tools/running-localstack/lstk/snapshots/#snapshot 301
+/aws/capabilities/state-management/cli-commands/ /aws/developer-tools/running-localstack/lstk/snapshots/#snapshot 301
 /aws/capabilities/state-management/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301
 /aws/capabilities/state-management/export-import-state/ /aws/developer-tools/snapshots/saving-snapshots-locally/ 301
 /aws/capabilities/state-management/ /aws/developer-tools/snapshots/ 301
 /aws/developer-tools/snapshots/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301
 /aws/developer-tools/snapshots/export-import-state/ /aws/developer-tools/snapshots/saving-snapshots-locally/ 301
-/aws/developer-tools/snapshots/cli-commands /aws/developer-tools/running-localstack/lstk/#snapshot 301
-/aws/developer-tools/snapshots/cli-commands/ /aws/developer-tools/running-localstack/lstk/#snapshot 301
+/aws/developer-tools/snapshots/cli-commands /aws/developer-tools/running-localstack/lstk/snapshots/#snapshot 301
+/aws/developer-tools/snapshots/cli-commands/ /aws/developer-tools/running-localstack/lstk/snapshots/#snapshot 301
 /aws/developer-tools/snapshots/launchpad /aws/developer-tools/snapshots/ 301
 /aws/developer-tools/snapshots/launchpad/ /aws/developer-tools/snapshots/ 301
 /aws/capabilities/state-management/launchpad /aws/developer-tools/snapshots/ 301
@@ -1080,8 +1080,8 @@
 /aws/configuration/security-testing/iam-policy-stream /aws/developer-tools/security-testing/iam-policy-stream/ 301
 /aws/configuration/security-testing/iam-policy-stream/ /aws/developer-tools/security-testing/iam-policy-stream/ 301
 /aws/configuration/state-management/ /aws/developer-tools/snapshots/ 301
-/aws/configuration/state-management/cli-commands /aws/developer-tools/running-localstack/lstk/#snapshot 301
-/aws/configuration/state-management/cli-commands/ /aws/developer-tools/running-localstack/lstk/#snapshot 301
+/aws/configuration/state-management/cli-commands /aws/developer-tools/running-localstack/lstk/snapshots/#snapshot 301
+/aws/configuration/state-management/cli-commands/ /aws/developer-tools/running-localstack/lstk/snapshots/#snapshot 301
 /aws/configuration/state-management/cloud-pods /aws/developer-tools/snapshots/cloud-pods/ 301
 /aws/configuration/state-management/cloud-pods/ /aws/developer-tools/snapshots/cloud-pods/ 301
 /aws/configuration/state-management/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301

src/content/docs/aws/ci-pipelines/best-practices.mdx

@@ -94,7 +94,7 @@ env  = ["ci"]     # Apply the [env.ci] profile below
 DEBUG = "1"
 ```
 
-See the [configuration reference](/aws/developer-tools/running-localstack/lstk/#configuration) for every available field.
+See the [configuration reference](/aws/developer-tools/running-localstack/lstk/configuration/) for every available field.
 
 Keep a single `.lstk/config.toml` for local development and CI where you can.
 However, if a CI job needs different settings, pass an alternative file with `lstk --config ./ci/lstk.toml start`.
@@ -112,7 +112,7 @@ It pulls the container image if needed, validates your license, starts the conta
 If startup fails, the command exits with a non-zero return code, causing your CI job to fail.
 
 For machine-readable output, add the global `--json` flag to any command.
-See [structured output](/aws/developer-tools/running-localstack/lstk/#structured-output) and [exit codes](/aws/developer-tools/running-localstack/lstk/#exit-codes) if your pipeline needs to inspect results programmatically.
+See [structured output](/aws/developer-tools/running-localstack/lstk/automation/#structured-output) and [exit codes](/aws/developer-tools/running-localstack/lstk/automation/#exit-codes) if your pipeline needs to inspect results programmatically.
 
 ## Seed state from Infrastructure as Code
 

src/content/docs/aws/ci-pipelines/codebuild.md

@@ -76,7 +76,7 @@ phases:
 ...
 ```
 
-Settings that apply to every run belong in an [`[env.*]` profile](/aws/developer-tools/running-localstack/lstk/#configuration) in a `.lstk/config.toml` committed to your repository, which also lets you pin the image tag.
+Settings that apply to every run belong in an [`[env.*]` profile](/aws/developer-tools/running-localstack/lstk/configuration/) in a `.lstk/config.toml` committed to your repository, which also lets you pin the image tag.
 Read more about the [configuration options](/aws/customization/configuration-options) of LocalStack.
 
 ### Dump LocalStack logs
@@ -192,7 +192,7 @@ cache:
   toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit
   ```
 
-  To resolve this, either use your Docker Hub account credentials to pull the image, or point `lstk` at LocalStack's public ECR mirror with the [`image` field](/aws/developer-tools/running-localstack/lstk/#custom-container-image) in `.lstk/config.toml`:
+  To resolve this, either use your Docker Hub account credentials to pull the image, or point `lstk` at LocalStack's public ECR mirror with the [`image` field](/aws/developer-tools/running-localstack/lstk/configuration/#custom-container-image) in `.lstk/config.toml`:
 
   ```toml
   [[containers]]

src/content/docs/aws/ci-pipelines/github-actions.md

@@ -46,7 +46,7 @@ You can then install `lstk` and start the emulator, passing the secret to the st
 ```
 
 `lstk start` pulls the image, validates your license, and returns only once the emulator is ready, so no separate wait step is needed.
-To pin the image tag, commit a [`.lstk/config.toml`](/aws/developer-tools/running-localstack/lstk/#configuration) to your repository rather than passing it on the command line.
+To pin the image tag, commit a [`.lstk/config.toml`](/aws/developer-tools/running-localstack/lstk/configuration/) to your repository rather than passing it on the command line.
 Where several steps run `lstk`, set `LOCALSTACK_AUTH_TOKEN` once at the job level instead of repeating it on every step.
 `lstk setup aws` writes a `localstack` AWS profile for the runner's `aws` binary to use. It is optional, but without it `lstk` notes on every call that no profile was found.
 
@@ -65,7 +65,7 @@ For example:
 ```
 
 You can add extra configuration options as further `LOCALSTACK_`-prefixed variables.
-Settings that apply to every run belong in an [`[env.*]` profile](/aws/developer-tools/running-localstack/lstk/#configuration) in `.lstk/config.toml` instead.
+Settings that apply to every run belong in an [`[env.*]` profile](/aws/developer-tools/running-localstack/lstk/configuration/) in `.lstk/config.toml` instead.
 
 ### Dump Localstack logs
 

src/content/docs/aws/connecting/infrastructure-as-code/aws-cdk.md

@@ -14,7 +14,7 @@ The AWS Cloud Development Kit (CDK) is an Infrastructure-as-Code (IaC) tool usin
 
 ## AWS CDK CLI for LocalStack
 
-[`lstk cdk`](/aws/developer-tools/running-localstack/lstk/#cdk) proxies the [AWS CDK](https://github.com/aws/aws-cdk) library against local APIs provided by LocalStack. It requires the AWS CDK CLI version `2.177.0` or newer on your `PATH`.
+[`lstk cdk`](/aws/developer-tools/running-localstack/lstk/aws-and-iac-commands/#cdk) proxies the [AWS CDK](https://github.com/aws/aws-cdk) library against local APIs provided by LocalStack. It requires the AWS CDK CLI version `2.177.0` or newer on your `PATH`.
 
 :::note
 `lstk cdk` supersedes the older [`cdklocal` wrapper script](/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts#cdklocal), which is deprecated but still available if you need it.
@@ -75,7 +75,7 @@ lstk cdk deploy
 > Do you wish to deploy these changes (y/n)? y
 ```
 
-Once the deployment is done, you can inspect the created resources via the [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command line
+Once the deployment is done, you can inspect the created resources via the [`lstk aws`](/aws/developer-tools/running-localstack/lstk/aws-and-iac-commands/#aws) command line
 
 ```bash
 lstk aws sns list-topics

src/content/docs/aws/connecting/infrastructure-as-code/aws-sam.md

@@ -12,7 +12,7 @@ The AWS Serverless Application Model (SAM) is an open-source framework for devel
 It uses a simplified syntax to define functions, APIs, databases, and event source mappings.
 When you deploy, SAM converts its syntax into AWS CloudFormation syntax, helping you create serverless applications more quickly.
 
-LocalStack can work with SAM using [`lstk sam`](/aws/developer-tools/running-localstack/lstk/#sam), which lets you deploy SAM applications on LocalStack.
+LocalStack can work with SAM using [`lstk sam`](/aws/developer-tools/running-localstack/lstk/aws-and-iac-commands/#sam), which lets you deploy SAM applications on LocalStack.
 This guide explains how to set up local AWS resources using `lstk sam`.
 
 ## `lstk sam`

src/content/docs/aws/connecting/infrastructure-as-code/cloud-custodian.md

@@ -16,7 +16,7 @@ You can use Cloud Custodian with LocalStack by just specifying the Cloud Custodi
 
 ## Getting started
 
-This guide is designed for users who are new to Cloud Custodian and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command.
+This guide is designed for users who are new to Cloud Custodian and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/aws-and-iac-commands/#aws) command.
 
 Start your LocalStack container using your preferred method.
 We will demonstrate how you can spin up an EC2 instance and tag it with the key `Custodian`, and then use Cloud Custodian to stop the instance.

src/content/docs/aws/connecting/infrastructure-as-code/crossplane.md

@@ -194,7 +194,7 @@ crossplane-test-bucket   True    True     crossplane-test-bucket   30s
 ```
 
 ...
-and the bucket it should also be visible when querying the local S3 buckets in LocalStack via [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws):
+and the bucket it should also be visible when querying the local S3 buckets in LocalStack via [`lstk aws`](/aws/developer-tools/running-localstack/lstk/aws-and-iac-commands/#aws):
 
 ```bash
 lstk aws s3 ls

src/content/docs/aws/connecting/infrastructure-as-code/former2.md

@@ -26,7 +26,7 @@ These outputs enable you to redeploy your resources while spinning a new LocalSt
 
 ## Getting started
 
-This guide is designed for users new to Former2 and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command.
+This guide is designed for users new to Former2 and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/aws-and-iac-commands/#aws) command.
 We will demonstrate how you can create local AWS resources using LocalStack, and import a CloudFormation output via Former2.
 
 ### Install Former2

src/content/docs/aws/connecting/infrastructure-as-code/terraform.mdx

@@ -17,7 +17,7 @@ HCL is a domain-specific language designed for writing configurations that defin
 LocalStack supports Terraform via the [AWS provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) through [custom service endpoints](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/guides/custom-service-endpoints#localstack).
 You can configure Terraform to use LocalStack in two ways:
 
-- Using [`lstk terraform`](/aws/developer-tools/running-localstack/lstk/#terraform) (alias `lstk tf`) to automatically configure the service endpoints for you.
+- Using [`lstk terraform`](/aws/developer-tools/running-localstack/lstk/aws-and-iac-commands/#terraform) (alias `lstk tf`) to automatically configure the service endpoints for you.
 - Manually configuring the service endpoints in your Terraform configuration with additional maintenance.
 
 In this guide, we will demonstrate how you can create local AWS resources using Terraform and LocalStack, by using `lstk terraform` and a manual configuration example.

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

@@ -113,4 +113,4 @@ 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.
+Run [`lstk volume path`](/aws/developer-tools/running-localstack/lstk/lifecycle-commands/#volume) to print the resolved directory.

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

@@ -28,7 +28,7 @@ DEBUG = "1"
 lstk start
 ```
 
-See [Passing environment variables to the container](/aws/developer-tools/running-localstack/lstk#passing-environment-variables-to-the-container) for details.
+See [Passing environment variables to the container](/aws/developer-tools/running-localstack/lstk/configuration/#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`.
@@ -61,7 +61,7 @@ Options that affect the core LocalStack system.
 ## CLI
 
 `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.
+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
 

src/content/docs/aws/customization/kubernetes/openshift.md

@@ -23,7 +23,7 @@ If you have any questions or uncertainties regarding the licensing implications,
 
 ## Getting started
 
-This guide is designed for users new to LocalStack and assumes basic knowledge of the AWS CLI and our [`lstk aws` AWS CLI proxy](/aws/developer-tools/running-localstack/lstk#aws).
+This guide is designed for users new to LocalStack and assumes basic knowledge of the AWS CLI and our [`lstk aws` AWS CLI proxy](/aws/developer-tools/running-localstack/lstk/aws-and-iac-commands/#aws).
 As a general prerequisite, you should have access to the [OpenShift Web Console](https://docs.openshift.com/container-platform/4.14/web_console/web-console-overview.html).
 
 We will demonstrate how you can create local AWS resources using LocalStack using the AWS CLI.
@@ -93,7 +93,7 @@ Since we are running LocalStack on OpenShift, we need to specify the route URL o
 The flag takes precedence over the environment variable.
 :::
 
-You can further use the other `lstk` tool proxies, such as [`lstk cdk`](/aws/developer-tools/running-localstack/lstk#cdk), [`lstk sam`](/aws/developer-tools/running-localstack/lstk#sam), and [`lstk terraform`](/aws/developer-tools/running-localstack/lstk#terraform), to interact with the deployment.
+You can further use the other `lstk` tool proxies, such as [`lstk cdk`](/aws/developer-tools/running-localstack/lstk/aws-and-iac-commands/#cdk), [`lstk sam`](/aws/developer-tools/running-localstack/lstk/aws-and-iac-commands/#sam), and [`lstk terraform`](/aws/developer-tools/running-localstack/lstk/aws-and-iac-commands/#terraform), to interact with the deployment.
 As with `lstk aws`, set `LSTK_ENDPOINT_URL` or pass `--endpoint-url` to point these at the route URL instead of a local emulator.
 
 ### Deleting the LocalStack deployment

src/content/docs/aws/customization/other-installations/enterprise-image.md

@@ -39,7 +39,7 @@ This offline functionality is enabled by:
     lstk start
     ```
 
-    See [Custom container image](/aws/developer-tools/running-localstack/lstk#custom-container-image) for details, including how `lstk` falls back to a locally present image when a pull fails.
+    See [Custom container image](/aws/developer-tools/running-localstack/lstk/configuration/#custom-container-image) for details, including how `lstk` falls back to a locally present image when a pull fails.
 
 ## "Online" vs "Offline" image