Currently AWS SAM CLI's command help text per command does not have a common structure, they all follow different formats without consistency.
Current state of the world as of v1.75.0 for one of the commands. It is a giant wall of text.
Usage: sam sync [OPTIONS]
Update/Sync local artifacts to AWS
By default, the sync command runs a full stack update. You can specify
--code or --watch to switch modes. � Sync also supports nested stacks and
nested stack resources. For example
$ sam sync --code --stack-name {stack} --resource-id \
{ChildStack}/{ResourceId}
Running --watch with --code option will provide a way to run code
synchronization only, that will speed up start time and will skip any
template change. Please remember to update your deployed stack by running
without --code option.
$ sam sync --code --watch --stack-name {stack}
Options:
--config-env TEXT The environment name specifying the default
parameter values in the configuration file
to use. Its default value is 'default'. For
more information about configuration files,
see: https://docs.aws.amazon.com/serverless-
application-
model/latest/developerguide/serverless-sam-
cli-config.html.
--config-file TEXT The path and file name of the configuration
file containing default parameter values to
use. Its default value is 'samconfig.toml'
in project directory. For more information
about configuration files, see:
https://docs.aws.amazon.com/serverless-
application-
model/latest/developerguide/serverless-sam-
cli-config.html.
-t, --template-file, --template PATH
AWS SAM template file. [default:
template.[yaml|yml|json]]
--code Sync code resources. This includes Lambda
Functions, API Gateway, and Step Functions.
--watch Watch local files and automatically sync
with remote.
--resource-id TEXT Sync code for all the resources with the ID.
To sync a resource within a nested stack,
use the following pattern
{ChildStack}/{logicalId}.
--resource [AWS::Serverless::Function|AWS::Lambda::Function|AWS::Serverless::LayerVersion|AWS::Lambda::LayerVersion|AWS::Serverless::Api|AWS::ApiGateway::RestApi|AWS::Serverless::HttpApi|AWS::ApiGatewayV2::Api|AWS::Serverless::StateMachine|AWS::StepFunctions::StateMachine]
Sync code for all resources of the given
resource type. Accepted values are
['AWS::Serverless::Function',
'AWS::Lambda::Function',
'AWS::Serverless::LayerVersion',
'AWS::Lambda::LayerVersion',
'AWS::Serverless::Api',
'AWS::ApiGateway::RestApi',
'AWS::Serverless::HttpApi',
'AWS::ApiGatewayV2::Api',
'AWS::Serverless::StateMachine',
'AWS::StepFunctions::StateMachine']
--dependency-layer / --no-dependency-layer
This option separates the dependencies of
individual function into another layer, for
speeding up the sync.process
--stack-name TEXT The name of the AWS CloudFormation stack
you're deploying to. If you specify an
existing stack, the command updates the
stack. If you specify a new stack, the
command creates it. [required]
-s, --base-dir DIRECTORY Resolve relative paths to function's source
code with respect to this folder. Use this
if SAM template and your source code are not
in same enclosing folder. By default,
relative paths are resolved with respect to
the SAM template's location
-u, --use-container If your functions depend on packages that
have natively compiled dependencies, use
this flag to build your function inside an
AWS Lambda-like Docker container
--image-repository ECR repo uri where this command uploads the
image artifacts that are referenced in your
template.
--image-repositories Specify mapping of Function Logical ID to
ECR Repo uri, of the form
Function_Logical_ID=ECR_Repo_Uri.This option
can be specified multiple times.
--s3-bucket TEXT The name of the S3 bucket where this command
uploads the artifacts that are referenced in
your template.
--s3-prefix TEXT A prefix name that the command adds to the
artifacts name when it uploads them to the
S3 bucket. The prefix name is a path name
(folder name) for the S3 bucket.
--kms-key-id TEXT The ID of an AWS KMS key that the command
uses to encrypt artifacts that are at rest
in the S3 bucket.
--role-arn TEXT The Amazon Resource Name (ARN) of an AWS
Identity and Access Management (IAM) role
that AWS CloudFormation assumes when
executing the change set.
--parameter-overrides Optional. A string that contains AWS
CloudFormation parameter overrides encoded
as key=value pairs.For example, 'ParameterKe
y=KeyPairName,ParameterValue=MyKey Parameter
Key=InstanceType,ParameterValue=t1.micro' or
KeyPairName=MyKey InstanceType=t1.micro
--debug Turn on debug logging to print debug message
generated by AWS SAM CLI and display
timestamps.
--profile TEXT Select a specific profile from your
credential file to get AWS credentials.
--region TEXT Set the AWS Region of the service (e.g. us-
east-1).
--metadata Optional. A map of metadata to attach to ALL
the artifacts that are referenced in your
template.
--notification-arns LIST Amazon Simple Notification Service
topicAmazon Resource Names (ARNs) that
AWS CloudFormation associates withthe stack.
--tags A list of tags to associate with the stack
that is created or updated.AWS
CloudFormation also propagates these tags to
resources in the stack if the resource
supports it.
--capabilities LIST A list of capabilities that you must specify
before AWS Cloudformation can create certain
stacks. Some stack templates might include
resources that can affect permissions in
your AWS account, for example, by creating
new AWS Identity and Access Management (IAM)
users. For those stacks, you must explicitly
acknowledge their capabilities by specifying
this parameter. The only valid valuesare
CAPABILITY_IAM and CAPABILITY_NAMED_IAM. If
you have IAM resources, you can specify
either capability. If you have IAM resources
with custom names, you must specify
CAPABILITY_NAMED_IAM. If you don't specify
this parameter, this action returns an
InsufficientCapabilities error.
-h, --help Show this message and exit.
Users would probably have a ton of questions based on that help text. Some things that come up top of mind are below.
- Which options are required?
- What are the options that are AWS infra related? AWS Credentials related?
- Which ones are about additional information for developers?
- How can options be ordered such that is about incremental exposure to complexity?
All help text will be following a certain structure like below.
Usage: **sam sub-command** [OPTIONS]
1-liner explanation of what the sub-command does.
It should directly map to the lifecycle shown in root help text.
Examples:
```$sam sub-command --options```
**This command does not require/requires access to AWS credentials.**
More detailed explanation.
Workflows:
$ sam command -> **sam sub-command**
Acronyms:
IAM : Identity and Access Management.
ARN: Amazon Resource Name.
SNS: Simple Notification Service.
ECR: Elastic Container Registy
KMS: Key Management Service.
Options:
**Required Options:**
...
AWS Credential Options: (Ordering changes on a per command basis)
....
Configuration Options:
....
Infrastructure Options:
....
Additional Options:
....
Verbosity Options:
....
The sync help text could be changed to look like below. Only the options are showcased here.
Usage: sam sync [OPTIONS]
NEW! Sync an AWS SAM Project to AWS.
Examples:
$ sam sync --code --stack-name {stack} --resource-id \
{ChildStack}/{ResourceId}
$ sam sync --code --watch --stack-name {stack}
By default, the sync command runs a full AWS Cloudformation stack update. You can specify
--code or --watch to switch modes. Sync also supports nested stacks and
nested stack resources.
Running --watch with --code option will provide a way to run code
synchronization only, that will speed up start time and will skip any
template change. Please remember to update your deployed stack by running
without --code option.
**This command requires access to AWS credentials.**
Acronyms:
IAM: Identity and Access Management.
ARN: Amazon Resource Name.
SNS: Simple Notification Service.
ECR: Elastic Container Registy
KMS: Key Management Service.
Options:
Required Options:
-t, --template-file, --template PATH AWS SAM template file. [default: template.[yaml|yml|json]]
--stack-name TEXT Name of the AWS CloudFormation stack.
AWS Credential Options:
Exploratory DESIGN NOTE: How can we streamline credentials
--profile TEXT Named profile for AWS credentials.
--region TEXT Set the AWS Region. (e.g. us-east-1).
Infrastructure Options:
--parameter-overrides String that contains AWS CloudFormation parameter overrides encoded as
key=value pairs.
For example, 'ParameterKey=KeyPairName,ParameterValue=MyKey
ParameterKey=InstanceType,ParameterValue=t1.micro' or KeyPairName=MyKey
InstanceType=t1.micro
--capabilities LIST List of capabilities that one must specify before AWS Cloudformation can create
certain stacks. Valid values: ["CAPABILITY_IAM", "CAPABILITY_NAMED_IAM"]
More info at: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/acknowledging-application-capabilities.html
--s3-bucket TEXT AWS S3 bucket where artifacts referenced in your template are uploaded.
--s3-prefix TEXT Prefix name that is added to the artifact's name when it is uploaded to
the AWS S3 bucket.
--image-repository AWS ECR repository URI where referenced image artifacts are uploaded.
--image-repositories Mapping of Function Logical ID to AWS ECR Repository URI
Example: Function_Logical_ID=ECR_Repo_Uri.
This option can be specified multiple times.
--kms-key-id TEXT ID of an AWS KMS key that is used to encrypt artifacts that are at rest
in the AWS S3 bucket.
--role-arn TEXT ARN of an IAM role that AWS CloudFormation assumes when executing the change set.
--notification-arns LIST ARNs of SNS topics that AWS CloudFormation associates with the stack.
--tags List of tags to associate with the stack.
--metadata Map of metadata to attach to ALL the artifacts that are referenced in
the template.
Configuration Options:
Learn more about configuration files at: https://docs.aws.amazon.com/serverless-application-
model/latest/developerguide/serverless-sam-cli-config.html.
--config-file TEXT Configuration file containing default parameter values. [default:'samconfig.toml']
--config-env TEXT Environment name specifying default parameter values in the configuration
file. [default: "default"]
Additional Options:
--dependency-layer / --no-dependency-layer
Separate dependencies of an individual function into a Lambda layer
for improving performance.
--watch Watch local files and automatically sync with cloud.
--code Sync **ONLY** code resources. This includes AWS Lambda Functions, API Gateway, and Step
Functions.
--resource-id TEXT Sync code for all the resources with the Logical ID. To sync a resource within a nested
stack, use the following pattern {ChildStack}/{logicalId}.
--resource RESOURCE Sync code for all resources of the given resource type. Accepted values are
['AWS::Serverless::Function', 'AWS::Lambda::Function',
'AWS::Serverless::LayerVersion', 'AWS::Lambda::LayerVersion',
'AWS::Serverless::Api', 'AWS::ApiGateway::RestApi', 'AWS::Serverless::HttpApi',
'AWS::ApiGatewayV2::Api', 'AWS::Serverless::StateMachine',
'AWS::StepFunctions::StateMachine']
-u, --use-container Build functions within AWS Lambda-like Docker container.
-s, --base-dir DIRECTORY Resolve relative paths to AWS SAM application from base directory.
Verbosity Options:
--debug Debug logging to print debug message generated by AWS SAM CLI and display
timestamps.
Here's a look at revamped sam build help text.
Usage: sam build [OPTIONS] [RESOURCE_LOGICAL_ID]
Build your AWS serverless function code.
To use this command, update the AWS SAM template to specify the path
to function's source code in the resource's Code or CodeUri property.
To build on one's workstation, run this command in folder containing
AWS SAM template. Built artifacts will be written to .aws-sam/build folder
Examples:
$ sam build
To build within an AWS Lambda like Docker container.
$ sam build --use-container
To build with inline environment variables within build containers.
$ sam build --use-container --container-env-var Function.ENV_VAR=value --container-env-var GLOBAL_ENV_VAR=value
To build with environment variables within build containers.
$ sam build --use-container --container-env-var-file env.json
To build & run functions locally.
$ sam build && sam local invoke
To build and package for deployment.
$ sam build && sam package --s3-bucket <bucketname>
To build only an individual resource (function or layer) located in the SAM
template. Downstream SAM package and deploy will deploy only this resource
$ sam build MyFunction
Supported Runtimes:
1. Python 3.7, 3.8, 3.9 using PIP
2. Nodejs 18.x, 16.x, 14.x, 12.x using NPM
3. Ruby3.2 using Bundler
4. Java 8, Java 11 using Gradle and Maven
5. Dotnetcore3.1, Dotnet6 using Dotnet CLI (without --use-container flag)
6. Go 1.x using Go Modules (without --use-container flag)
Options:
Required Options:
-t, --template-file, --template AWS SAM template file. [default: template.[yaml|yml|json]]
Configuration Options:
Learn more about configuration files at:
https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-config.html.
--config-file TEXT Configuration file containing default parameter values. [default:'samconfig.toml']
--config-env TEXT Environment name specifying default parameter values in the configuration
file. [default: "default"]
AWS Credential Options:
Exploratory DESIGN NOTE: How can we streamline credentials
--profile TEXT Named profile for AWS credentials.
--region TEXT Set the AWS Region. (e.g. us-east-1).
Container Options:
-u, --use-container For functions that depend on packages which
have natively compiled dependencies, use
this flag to build functions inside an
AWS Lambda-like Docker container
-e, --container-env-var TEXT Input environment variables through command
line to pass into build containers
Example: sam build --use-
container --container-env-var
Func1.VAR1=value1 --container-env-var
VAR2=value2
-ef, --container-env-var-file Environment variable json file
(env_vars.json) to pass into build
containers.
-bi, --build-image TEXT Container image URIs for building
functions/layers. One can specify for all
functions/layers with just the image URI
(--build-image public.ecr.aws/sam/build-
nodejs18.x:latest). One can also specify for each
individual function with (--build-image
FunctionLogicalID=public.ecr.aws/sam/build-
nodejs18.x:latest). A combination of the two
can be used. If a function does not have
build image specified or an image URI for
all functions, the default AWS SAM CLI build
images will be used.
--skip-pull-image Skip pulling down the latest Docker image
for Lambda runtime.
--docker-network TEXT Name or ID of an existing
docker network for AWS Lambda docker containers
to connect to, along with the default
bridge network.
If not specified, the Lambda
containers will only connect to the default
bridge docker network.
Extension Options:
--hook-name TEXT ID of the hook package to be used to
extend the AWS SAM CLI commands functionality.
Available Hook Names ['terraform']
--skip-prepare-infra Skip infrastructure preparation
if there have not been any
infrastructure changes.
`--hook-name` is required to use this option.
Build Stratergy Options:
-x, --exclude TEXT Name of the resource(s) to exclude from the
SAM CLI build.
-p, --parallel Enable parallel builds.
-m, --manifest PATH Path to a custom dependency manifest (e.g.,
package.json).
-c, --cached / --no-cached Enable cached builds.
Note: AWS SAM does not evaluate whether
changes have been made to third party
modules that your project depends on, where
you have not provided a specific version.
For example, if your Python function
includes a requirements.txt file with the
following entry requests=1.x and the latest
request module version changes from 1.1 to
1.2, SAM will not pull the latest version
until you run a non-cached build.
Artifact Location Options:
-b, --build-dir DIRECTORY Directory where the built artifacts
will be stored. This directory will be first
removed before starting a build.
-cd, --cache-dir DIRECTORY Directory where the cache artifacts will be
stored. The
default cache directory is .aws-sam/cache
-s, --base-dir DIRECTORY Resolve relative paths to AWS SAM application from base directory.
Template Options:
--parameter-overrides String that contains AWS
CloudFormation parameter overrides encoded
as key=value pairs.For example, 'ParameterKe
y=KeyPairName,ParameterValue=MyKey Parameter
Key=InstanceType,ParameterValue=t1.micro' or
KeyPairName=MyKey InstanceType=t1.micro
Beta Options:
--beta-features / --no-beta-features
Enable beta features.
Verbosity Options:
--debug Turn on debug logging to print debug message
generated by AWS SAM CLI and display
timestamps.
-h, --help Show this message and exit.
- The success criteria for the change is less time spent on the help text to understand which options are useful.
- Increased confidence that the tool will help the user move in the right direction for their application.
CLI interface will remain the same.
N/A
There will be a separate implementation PR to showcase the changes, but it will use click to override commands options and help text.
N/A
What new dependencies (libraries/cli) does this change require?
- No new dependencies
What other Docker container images are you using?
N/A
Are you creating a new HTTP endpoint? If so explain how it will be created & used
N/A
Are you connecting to a remote API? If so explain how is this connection secured
N/A
Are you reading/writing to a temporary folder? If so, what is this used for and when do you clean up?
N/A
How do you validate new samconfig.toml configuration?
N/A
- Send a Pull Request with this design document
- Build the command line interface
- Build the underlying library
- Unit tests
- Functional Tests
- Integration tests
- Run all tests on Windows
- Update documentation