Fix format inconsistency in SAM CLI help text by vicheey · Pull Request #8663 · aws/aws-sam-cli

vicheey · 2026-02-17T16:55:38Z

Which issue(s) does this change fix?

Fix format inconsistency issue across SAM CLI help text.

Why is this change necessary?

SAM CLI commands had inconsistent help text formatting with different section structures, spacing, and organization. Some commands used custom formatters while others used the base CoreCommand pattern. This inconsistency made the CLI harder to read and maintain.

How does it address the issue?

Migrated all commands to use the CoreCommand pattern with consistent section structure
Standardized option grouping across commands (e.g., "AWS Credential Options", "Configuration Options", "Other Options")
Implemented nested indented_section formatting for example section with descriptive titles
Used RowDefinition(text="\n") for consistent spacing before command in example sections
Removed 19 custom formatter files.
Added proper type hints (-> Dict, -> CommandHelpTextFormatter, -> None) to satisfy mypy
Created core command structures for pipeline init and bootstrap commands

What side effects does this change have?

Help text output format changes for all commands (improved consistency and readability)
Deleted 19 custom formatter files, reducing code duplication
All existing tests updated to match new format expectations
Added 2 new test files for pipeline commands

Mandatory Checklist

PRs will only be reviewed after checklist is complete

Review the generative AI contribution guidelines
Add input/output type hints to new functions/methods
Write design document if needed ([Do I need to write a design document?](https://github.com/aws/aws-sam-cli/blob/develop/DEVELOPMENT_GUIDE.md#
design-document))
Write/update unit tests
Write/update integration tests
Write/update functional tests if needed
make pr passes
make update-reproducible-reqs if dependencies were changed
Write documentation

Step to Verify the Output

1. Pull the branch and set up environment

# Pull the branch
git fetch origin
git checkout <branch-name>

# Set up Python virtual environment (if not already done)
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Initialize development environment
make init

2. Verify the fix

Run the following interactive script to review help text for all commands. The script will pause after each command so you can verify:

Examples sections have single-line spacing (no blank lines between examples)
Text wraps properly with right padding (doesn't extend to terminal edge)
All formatting looks clean and readable

#!/bin/bash

# Interactive help text verification script
# Press ENTER after reviewing each command's help output

echo "==================================================================="
echo "SAM CLI Help Text Verification"
echo "==================================================================="
echo ""
echo "This script will display help text for each SAM CLI command."
echo "After each command, press ENTER to continue to the next one."
echo ""
echo "What to verify:"
echo "  ✓ Examples sections have single-line spacing (no double-spacing)"
echo "  ✓ Text uses full terminal width with proper right padding"
echo "  ✓ No text wrapping at terminal edge"
echo ""
read -p "Press ENTER to start..."

commands=(
    "samdev -h"
    "samdev init -h"
    "samdev build -h"
    "samdev local -h"
    "samdev local invoke -h"
    "samdev local start-api -h"
    "samdev local start-lambda -h"
    "samdev local generate-event -h"
    "samdev validate -h"
    "samdev deploy -h"
    "samdev delete -h"
    "samdev logs -h"
    "samdev traces -h"
    "samdev sync -h"
    "samdev package -h"
    "samdev publish -h"
    "samdev pipeline -h"
    "samdev list -h"
    "samdev docs -h"
    "samdev remote -h"
)

for cmd in "${commands[@]}"; do
    echo ""
    echo "==================================================================="
    echo "Command: $cmd"
    echo "==================================================================="
    echo ""
    eval "$cmd"
    echo ""
    echo "-------------------------------------------------------------------"
    read -p "Press ENTER to continue to next command..."
done

echo ""
echo "==================================================================="
echo "Verification Complete!"
echo "==================================================================="
echo ""
echo "All commands reviewed. If everything looks good, approve the PR!"

3. Save and run the script

# Save the script above to a file
cat > verify_help.sh << 'SCRIPT_END'
#!/bin/bash

# Interactive help text verification script
# Press ENTER after reviewing each command's help output

echo "==================================================================="
echo "SAM CLI Help Text Verification"
echo "==================================================================="
echo ""
echo "This script will display help text for each SAM CLI command."
echo "After each command, press ENTER to continue to the next one."
echo ""
echo "What to verify:"
echo "  ✓ Examples sections have single-line spacing (no double-spacing)"
echo "  ✓ Text uses full terminal width with proper right padding"
echo "  ✓ No text wrapping at terminal edge"
echo ""
read -p "Press ENTER to start..."

commands=(
    "samdev -h"
    "samdev init -h"
    "samdev build -h"
    "samdev local -h"
    "samdev local invoke -h"
    "samdev local start-api -h"
    "samdev local start-lambda -h"
    "samdev local generate-event -h"
    "samdev validate -h"
    "samdev deploy -h"
    "samdev delete -h"
    "samdev logs -h"
    "samdev traces -h"
    "samdev sync -h"
    "samdev package -h"
    "samdev publish -h"
    "samdev pipeline -h"
    "samdev list -h"
    "samdev docs -h"
    "samdev remote -h"
)

for cmd in "${commands[@]}"; do
    echo ""
    echo "==================================================================="
    echo "Command: $cmd"
    echo "==================================================================="
    echo ""
    eval "$cmd"
    echo ""
    echo "-------------------------------------------------------------------"
    read -p "✓ Verified? Press ENTER to continue to next command..."
done

echo ""
echo "==================================================================="
echo "Verification Complete!"
echo "==================================================================="
echo ""
echo "All commands reviewed. If everything looks good, approve the PR!"
SCRIPT_END

# Make it executable and run
chmod +x verify_help.sh
./verify_help.sh

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

reedham-aws · 2026-02-17T17:54:06Z

Do you have an example of what some of the changed commands look like before and after?

roger-zhangg · 2026-02-17T21:43:46Z

do you have a chance to remove the new tag from the main command help as well?

sam --help

  Learn:
    docs NEW!           Launch the AWS SAM CLI documentation in a browser.

  Create an App:
    init                Initialize an AWS SAM application.

  Develop your App:
    build               Build your AWS serverless function code.
    local               Run your AWS serverless function locally.
    validate            Validate an AWS SAM template.
    sync NEW!           Sync an AWS SAM project to AWS.
    remote NEW!         Invoke or send an event to cloud resources in your AWS
                        Cloudformation stack.

  Deploy your App:
    package             Package an AWS SAM application.
    deploy              Deploy an AWS SAM application.

  Monitor your App:
    logs                Fetch AWS Cloudwatch logs for AWS Lambda Functions or
                        Cloudwatch Log groups.
    traces              Fetch AWS X-Ray traces.

  And More:
    list NEW!           Fetch the state of your AWS serverless application.

valerena · 2026-02-19T19:47:53Z

I personally don't like all the extra space that some of the SAM CLI help outputs had, and now it looks like now we're unifying all the commands to have that extra space. (for example sam local --help)
old

$ sam local --help
Usage: sam local [OPTIONS] COMMAND [ARGS]...

  Run your Serverless application locally for quick development & testing

Options:
  -h, --help  Show this message and exit.

Commands:
  callback        Send callbacks to durable function executions
  execution       Manage durable function executions
  generate-event  Generate events for Lambda functions.
  invoke          Invoke AWS serverless functions locally.
  start-api       Run & test AWS serverless functions locally as a HTTP API.
  start-lambda    Emulate AWS serverless functions locally.

vs new

$ sam local --help

Usage: sam local [OPTIONS] COMMAND [ARGS]...

  Run your Serverless application locally for quick development & testing

Options:

  -h, --help  Show this message and exit.

Commands:

  callback (NEW!)    Send callbacks to durable function executions

  execution (NEW!)   Manage durable function executions

  generate-event     Generate events for Lambda functions.

  invoke             Invoke AWS serverless functions locally.

  start-api          Run & test AWS serverless functions locally as a HTTP API.

  start-lambda       Emulate AWS serverless functions locally.

Do you know why we have all the extra space? Is that a conscious decision?

valerena · 2026-02-19T19:50:30Z

Now in the code I see that it's not just "a format thing", but we explicitly add new lines everywhere. Do we like that?

vicheey · 2026-02-25T18:26:02Z

Now in the code I see that it's not just "a format thing", but we explicitly add new lines everywhere. Do we like that?

Before the changes, some command had space between option description while some didn't. For consistency, either add space or remove all space. I chose to add because it provided clear separation especially for multiline description.

Do you prefer no line like the before in here: #8663 (comment)?

reedham-aws

I admittedly didn't review all 138 files, but LGTM.

valerena

I really like the changes! I added a few comments of some minor things and some other "good to have", but that are not really necessary and we can think about doing them later.

valerena · 2026-03-04T22:25:40Z

samcli/commands/build/core/command.py

+            return CommandHelpTextFormatter(
+                additive_justification=3,
+                options=ALL_OPTIONS,
+                width=self.terminal_width,


I see in CommandHelpTextFormatter that if width is not passed it will use terminal_width anyway. Can we just not pass it from every formatter?

valerena · 2026-03-04T22:42:32Z

samcli/commands/build/core/command.py

    class CustomFormatterContext(Context):
-        formatter_class = BuildCommandHelpTextFormatter
+        def make_formatter(self):
+            return CommandHelpTextFormatter(
+                additive_justification=3,
+                options=ALL_OPTIONS,
+                width=self.terminal_width,
+                max_width=self.max_content_width,
+            )

    context_class = CustomFormatterContext


I see that this class is basically the same all the time except for the options (and some with additive_justification). It would be nice if we could have a function to create this class dynamically.

I'm not sure if this is the best syntax to do it, but something like this:

def create_custom_formatter_context(options, additive_justification=None): class CustomFormatterContext(Context): def make_formatter(self): return CommandHelpTextFormatter( additive_justification=additive_justification, options=options, max_width=self.max_content_width, ) return CustomFormatterContext

that you can then use like this:

from commands.common.formatters import create_custom_formatter_context ... ... ... context_class = create_custom_formatter_context(ALL_OPTIONS, additive_justification=3)

valerena · 2026-03-04T22:47:22Z

samcli/commands/delete/core/__init__.py

+"""
+Delete Core Command
+"""


The great majority of the __init__.py files for other commands don't have any contents (it's usually not very useful)

valerena · 2026-03-04T22:49:16Z

samcli/commands/deploy/core/options.py

+                name="Learn more about configuration files at: "
+                "https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-config.html."


We probably want this string defined once and used everywhere?

valerena · 2026-03-04T22:51:23Z

samcli/commands/pipeline/bootstrap/core/__init__.py

@@ -0,0 +1 @@
+"""Pipeline bootstrap core command"""


Same about the __init__.py file (don't add contents to it)

valerena · 2026-03-04T22:51:50Z

samcli/commands/publish/core/__init__.py

+"""
+Publish Command Core
+"""


Another __init__.py

valerena · 2026-03-04T22:53:18Z

samcli/commands/traces/core/__init__.py

+"""
+Traces Command Core
+"""


__init__.py

update help text to be have uniform format

ba7788f

vicheey marked this pull request as ready for review February 17, 2026 16:55

vicheey requested a review from a team as a code owner February 17, 2026 16:55

add header for example for sam sync help text

a81edfc

vicheey and others added 9 commits February 17, 2026 14:03

remove additive space that causes double blank lines

1ebb04a

format sam publish command help text

1c92e38

remove "NEW" from sam sync command

e352d0f

add formatting for sam traces -h

19817ef

remove NEW from sam docs -h

711b2b2

update samcli.json

e30cd85

fix test issue

49142c0

Merge branch 'develop' into fix-command-help-text

8b1d7ce

Merge branch 'develop' into fix-command-help-text

548ad3d

Merge branch 'develop' into fix-command-help-text

caa4fb5

vicheey added 4 commits February 27, 2026 10:48

remove new line between command description

c9719be

Merge branch 'develop' into fix-command-help-text

4f962f0

add write_text_rows() for allow single column row rendering

8ee25aa

fix terminal width issue

27d80fd

vicheey requested a review from Vandita2020 February 27, 2026 22:02

vicheey and others added 3 commits February 27, 2026 14:05

update samcli.json

389b77f

Merge branch 'develop' into fix-command-help-text

fe42cbf

Merge branch 'develop' into fix-command-help-text

21deb3b

reedham-aws approved these changes Mar 4, 2026

View reviewed changes

valerena reviewed Mar 4, 2026

View reviewed changes

		name="Learn more about configuration files at: "
		"https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-config.html."

Conversation

vicheey commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Which issue(s) does this change fix?

Why is this change necessary?

How does it address the issue?

What side effects does this change have?

Mandatory Checklist

Step to Verify the Output

1. Pull the branch and set up environment

2. Verify the fix

3. Save and run the script

Uh oh!

reedham-aws commented Feb 17, 2026

Uh oh!

roger-zhangg commented Feb 17, 2026

Uh oh!

valerena commented Feb 19, 2026

Uh oh!

valerena commented Feb 19, 2026

Uh oh!

vicheey commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

reedham-aws left a comment

Choose a reason for hiding this comment

Uh oh!

valerena left a comment

Choose a reason for hiding this comment

Uh oh!

valerena Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

valerena Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

valerena Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

valerena Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

valerena Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

valerena Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

valerena Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vicheey commented Feb 17, 2026 •

edited

Loading

vicheey commented Feb 25, 2026 •

edited

Loading