Skip to content

Migrate skills from legacy localstack CLI to lstk - #5

Open
remotesynth wants to merge 1 commit into
mainfrom
lstk-migration
Open

Migrate skills from legacy localstack CLI to lstk#5
remotesynth wants to merge 1 commit into
mainfrom
lstk-migration

Conversation

@remotesynth

@remotesynth remotesynth commented Sep 1, 2026

Copy link
Copy Markdown

tldr: As part of the official lstk launch, I wanted to replace the existing localstack, awslocal, cdklocal, tflocal, etc. CLI usage with lstk. There are some drawbacks to this given that some of the functionality covered here isn't yet supported in lstk, so there are some areas in which it is noted that alternative CLI tools will be necessary to use. This could cause some confusion, but still standardizes the majority of the functionality on lstk.


Replace the localstack CLI + awslocal/tflocal/cdklocal wrapper combination with the lstk CLI across all six skills and the README.

Behavioral change reviewers must not miss:

lstk only forwards host env vars prefixed with LOCALSTACK_. Every bare
DEBUG=1 localstack start -d in the old skills would silently do nothing
under lstk. All are now LOCALSTACK_DEBUG=1 lstk start. Note the inverse
trap: keys inside a config.toml [env.*] profile take NO prefix. Also,
lstk start already backgrounds -- there is no -d flag.

Command mappings applied:

localstack start/stop/status/logs -> lstk start/stop/status/logs
PERSISTENCE=1 -> lstk start --persist
awslocal -> lstk aws
tflocal -> lstk terraform (--region/--account
go before the subcommand)
cdklocal -> lstk cdk (requires CDK >= 2.177.0)
(new) -> lstk sam (requires SAM >= 1.95.0)
localstack state export/import -> lstk save / lstk load
localstack pod save/load -> lstk save pod: / lstk load pod:

Gaps where lstk is NOT usable, each documented in-skill and in a new README "Optional extra CLIs" table:

  • Extensions: no lstk extensions command suite exists. This is worse than it first appears. lstk volume path resolves to ~/Library/Caches/lstk/volume/localstack-aws, a DIFFERENT directory from the legacy ~/Library/Caches/localstack that extensions install into, so an emulator started by lstk will not load installed extensions at all. The extensions skill therefore stays on the legacy CLI end to end, and warns that the two CLIs conflict on port 4566.
  • Pulumi: no lstk proxy command. pulumilocal is still required.
  • SAM: lstk sam does not support image/container-based Lambda (ECR) deploys or nested CloudFormation stacks. samlocal is still required.
  • IAM policy generation: localstack aws iam stream / summary have no lstk equivalent. The IAM skill keeps them as the recommended path and falls back to lstk logs -v grepping only when the legacy CLI is absent.

Two further points of potential confusion for reviewers:

  • lstk always pulls localstack/localstack-pro and requires a license. The old state-management skill advertised "Pro required: No" for local snapshots; that column is now wrong and has been removed, with a note that the license applies regardless of snapshot backend.
  • lstk logs filters output by default, unlike localstack logs. Every place a skill greps for a specific line now uses lstk logs -v.

Legacy localstack references that remain in the tree are intentional: the extensions skill, the IAM stream/summary workflow, and migration notes.

Command surface was verified against the locally installed lstk binary's --help output, not the published docs alone.

Replace the localstack CLI + awslocal/tflocal/cdklocal wrapper combination
with the lstk CLI across all six skills and the README.

Behavioral change reviewers must not miss:

  lstk only forwards host env vars prefixed with LOCALSTACK_. Every bare
  `DEBUG=1 localstack start -d` in the old skills would silently do nothing
  under lstk. All are now `LOCALSTACK_DEBUG=1 lstk start`. Note the inverse
  trap: keys inside a config.toml [env.*] profile take NO prefix. Also,
  `lstk start` already backgrounds -- there is no -d flag.

Command mappings applied:

  localstack start/stop/status/logs   -> lstk start/stop/status/logs
  PERSISTENCE=1                       -> lstk start --persist
  awslocal <cmd>                      -> lstk aws <cmd>
  tflocal                             -> lstk terraform (--region/--account
                                         go before the subcommand)
  cdklocal                            -> lstk cdk (requires CDK >= 2.177.0)
  (new)                               -> lstk sam (requires SAM >= 1.95.0)
  localstack state export/import      -> lstk save / lstk load
  localstack pod save/load            -> lstk save pod: / lstk load pod:

Gaps where lstk is NOT usable, each documented in-skill and in a new
README "Optional extra CLIs" table:

  - Extensions: no `lstk extensions` command suite exists. This is worse
    than it first appears. `lstk volume path` resolves to
    ~/Library/Caches/lstk/volume/localstack-aws, a DIFFERENT directory from
    the legacy ~/Library/Caches/localstack that extensions install into, so
    an emulator started by lstk will not load installed extensions at all.
    The extensions skill therefore stays on the legacy CLI end to end, and
    warns that the two CLIs conflict on port 4566.
  - Pulumi: no lstk proxy command. pulumilocal is still required.
  - SAM: `lstk sam` does not support image/container-based Lambda (ECR)
    deploys or nested CloudFormation stacks. samlocal is still required.
  - IAM policy generation: `localstack aws iam stream` / `summary` have no
    lstk equivalent. The IAM skill keeps them as the recommended path and
    falls back to `lstk logs -v` grepping only when the legacy CLI is absent.

Two further points of potential confusion for reviewers:

  - lstk always pulls localstack/localstack-pro and requires a license. The
    old state-management skill advertised "Pro required: No" for local
    snapshots; that column is now wrong and has been removed, with a note
    that the license applies regardless of snapshot backend.
  - `lstk logs` filters output by default, unlike `localstack logs`. Every
    place a skill greps for a specific line now uses `lstk logs -v`.

Legacy `localstack` references that remain in the tree are intentional:
the extensions skill, the IAM stream/summary workflow, and migration notes.

Command surface was verified against the locally installed lstk binary's
--help output, not the published docs alone.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@remotesynth
remotesynth requested a review from whummer September 1, 2026 20:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant