Command Line Interface¶

Sceptre can be used as a command line tool. Running Sceptre without a sub-command will display help, showing a list of the available commands.

Autocomplete¶

To enable CLI autocomplete for subcommands and parameters execute the following command:

shell	command
bash	eval “$(_SCEPTRE_COMPLETE=source_bash sceptre)”
zsh	eval “$(_SCEPTRE_COMPLETE=source_zsh sceptre)”

Export Stack Outputs to Environment Variables¶

Stack outputs can be exported as environment variables with the command:

eval $(sceptre --ignore-dependencies list outputs STACKGROUP/STACK.yaml --export=envvar)

Note that Sceptre prepends the string SCEPTRE_ to the name of the environment variable:

env | grep SCEPTRE
SCEPTRE_<output_name>=<output_value>

Variable Handling¶

You can pass variables into your project using --var-file and --var.

Variables passed in with --var will overwrite any matching variables specified in --var-file. If you use multiple --var flags then the right-most --var will overwrite any matching --vars to the left. For example, in the following command

sceptre --var var1=one --var var2=two --var var1=three launch stack

var1 will equal three.

You can also use --var to overwrite nested keys in a --var-file. For example, given a variable file “vars.yaml”:

# vars.yaml
---
top:
  middle:
    nested: hello
  middle2:
    nested: world

we could overwrite nested: world to nested: hi using:

sceptre --var-file vars.yaml --var top.middle2.nested=hi launch stack

Note

Sceptre will load your entire project to build a full dependency graph. This means that all stacks that use variables will need to have a value provided to them - even if they are not in your command_path or are not a dependency. Using a –var-file with all variables set can help meet this requirement.

It is also possible to have keys merged according to a deep merge algorithm from successive var files, by specifying --merge-vars. So, if we had a second variable file “vars2.yaml”:

# other_vars.yaml
---
top:
  middle3:
    nested: more world

We could merge all of this together using:

sceptre --merge-vars --var-file vars.yaml --var-file other_vars.yaml launch stack

The top dictionary would then be expected to contain:

{
  "top": {
    "middle": {"nested": "hello"},
    "middle2": {"nested": "world"},
    "middle3": {"nested": "more world"}
  }
}

Command reference¶

Command options differ depending on the command, and can be found by running:

sceptre
sceptre --help
sceptre COMMAND --help

sceptre¶

Sceptre is a tool to manage your cloud native infrastructure deployments.

sceptre [OPTIONS] COMMAND [ARGS]...

Options

--version¶: Show the version and exit.

--debug¶: Turn on debug logging.

--dir <directory>¶: Specify sceptre directory.

--output <output>¶

The formatting style for command output.

Options: text | yaml | json

--no-colour¶: Turn off output colouring.

--var <var>¶: A variable to replace the value of an item in config file.

--var-file <var_file>¶: A YAML file of variables to replace the values of items in config files.

--ignore-dependencies¶: Ignore dependencies when executing command.

--merge-vars¶: Merge variables from successive –vars and var files

create¶

Creates a stack for a given config PATH. Or if CHANGE_SET_NAME is specified creates a change set for stack in PATH.

param path

Path to a Stack or StackGroup

type path

str

param change_set_name

A name of the Change Set - optional

type change_set_name

str

param yes

A flag to assume yes to all questions.

type yes

bool

param disable_rollback

A flag to disable cloudformation rollback.

sceptre create [OPTIONS] PATH [CHANGE_SET_NAME]

Options

-y, --yes¶: Assume yes to all questions.

--disable-rollback, --enable-rollback¶: Disable or enable the cloudformation automatic rollback

Arguments

PATH¶: Required argument

CHANGE_SET_NAME¶: Optional argument

delete¶

Deletes a stack for a given config PATH. Or if CHANGE_SET_NAME is specified deletes a change set for stack in PATH.

param path

Path to execute command on.

type path

str

param change_set_name

The name of the change set to use - optional

type change_set_name

str

param yes

Flag to answer yes to all CLI questions.

type yes

bool

sceptre delete [OPTIONS] PATH [CHANGE_SET_NAME]

Options

-y, --yes¶: Assume yes to all questions.

Arguments

PATH¶: Required argument

CHANGE_SET_NAME¶: Optional argument

describe¶

Commands for describing attributes of stacks.

sceptre describe [OPTIONS] COMMAND [ARGS]...

change-set¶

Describes the change set.

param path

Path to execute the command on.

type path

str

param change_set_name

Name of the Change Set to use.

type change_set_name

str

param verbose

A flag to display verbose output.

type verbose

bool

sceptre describe change-set [OPTIONS] PATH CHANGE_SET_NAME

Options

-v, --verbose¶: Display verbose output.

Arguments

PATH¶: Required argument

CHANGE_SET_NAME¶: Required argument

policy¶

Displays the stack policy used.

param path

Path to execute the command on.

type path

str

sceptre describe policy [OPTIONS] PATH

Arguments

PATH¶: Required argument

diff¶

Indicates the difference between the currently DEPLOYED stacks in the command path and

the stacks configured in Sceptre right now. This command will compare both the templates as well as the subset of stack configurations that can be compared. By default, only stacks that would be launched via the launch command will be diffed, but you can diff ALL stacks relevant to the passed command path if you pass the –all flag.

Some settings (such as sceptre_user_data) are not available in a CloudFormation stack description, so the diff will not be indicated. Currently compared stack configurations are:

parameters
notifications
cloudformation_service_role
stack_tags

Important: There are resolvers (notably !stack_output) that rely on other stacks to be already deployed when they are resolved. When producing a diff on Stack Configs that have such resolvers that point to non-deployed stacks, this presents a challenge, since this means those resolvers cannot be resolved. This particularly applies to stack parameters and when a stack’s template uses sceptre_user_data with resolvers in it. In order to continue to be useful when producing a diff in these conditions, this command will do the following:

1. If the resolver CAN be resolved, it will be resolved and the resolved value will be in the diff results. 2. If the resolver CANNOT be resolved, it will be replaced with a string that represents the resolver and its arguments. For example: !stack_output my_stack.yaml::MyOutput will resolve in the parameters to “{ !StackOutput(my_stack.yaml::MyOutput) }”.

Particularly in cases where the replaced value doesn’t work in the template as the template logic requires and causes an error, there is nothing further Sceptre can do and diffing will fail.

sceptre diff [OPTIONS] PATH

Options

-t, --type <differ>¶

The type of differ to use. Use “deepdiff” for recursive key/value comparison. “difflib” produces a more traditional “diff” result. Defaults to deepdiff.

Options: deepdiff | difflib

-s, --show-no-echo¶: If set, will display the unmasked values of NoEcho parameters generated LOCALLY (NoEcho parameters for deployed stacks will always be masked when retrieved from CloudFormation.). If not set (the default), parameters identified as NoEcho on the local template will be masked when presented in the diff.

-n, --no-placeholders¶: If set, no placeholder values will be supplied for resolvers that cannot be resolved.

-a, --all¶: If set, will perform diffing on ALL stacks, including ignored and obsolete ones; Otherwise, it will diff only stacks that would be created or updated when running the launch command.

Arguments

PATH¶: Required argument

drift¶

Commands for calling drift detection.

sceptre drift [OPTIONS] COMMAND [ARGS]...

detect¶

Detect stack drift and return stack drift status.

In the event that the stack does not exist, we return a DetectionStatus and StackDriftStatus of STACK_DOES_NOT_EXIST.

In the event that drift detection times out, we return a DetectionStatus and StackDriftStatus of TIMED_OUT.

The timeout is set at 5 minutes, a value that cannot be configured.

sceptre drift detect [OPTIONS] PATH

Arguments

PATH¶: Required argument

show¶

Show stack drift on deployed stacks.

In the event that the stack does not exist, we return a StackResourceDriftStatus of STACK_DOES_NOT_EXIST.

In the event that drift detection times out, we return a StackResourceDriftStatus of TIMED_OUT.

The timeout is set at 5 minutes, a value that cannot be configured.

sceptre drift show [OPTIONS] PATH

Options

-D, --drifted¶: Filter out in sync resources.

Arguments

PATH¶: Required argument

dump¶

Commands for dumping attributes of stacks.

sceptre dump [OPTIONS] COMMAND [ARGS]...

all¶

Dumps both the rendered (post-Jinja) Stack Configs and the template used for stack in PATH.

param path

Path to execute the command on.

type path

str

sceptre dump all [OPTIONS] PATH

Options

-n, --no-placeholders¶: If True, no placeholder values will be supplied for resolvers that cannot be resolved.

--to-file¶: If True, also dump the template to a local file.

Arguments

PATH¶: Required argument

config¶

Dump the rendered (post-Jinja) Stack Configs.

param path

Path to execute the command on or path to stack group

sceptre dump config [OPTIONS] PATH

Options

--to-file¶: If True, also dump the template to a local file.

Arguments

PATH¶: Required argument

template¶

Prints the template used for stack in PATH.

param path

Path to execute the command on.

type path

str

sceptre dump template [OPTIONS] PATH

Options

-n, --no-placeholders¶: If True, no placeholder values will be supplied for resolvers that cannot be resolved.

--to-file¶: If True, also dump the template to a local file.

Arguments

PATH¶: Required argument

estimate-cost¶

Prints a URI to STOUT that provides an estimated cost based on the resources in the stack. This command will also attempt to open a web browser with the returned URI.

param path

Path to execute the command on.

type path

str

sceptre estimate-cost [OPTIONS] PATH

Arguments

PATH¶: Required argument

execute¶

Executes a Change Set.

param path

Path to execute the command on.

type path

str

param change_set_name

Change Set to use.

type change_set_name

str

param yes

A flag to answer ‘yes’ too all CLI questions.

type yes

bool

sceptre execute [OPTIONS] PATH CHANGE_SET_NAME

Options

-y, --yes¶: Assume yes to all questions.

--disable-rollback, --enable-rollback¶: Disable or enable the cloudformation automatic rollback

Arguments

PATH¶: Required argument

CHANGE_SET_NAME¶: Required argument

fetch-remote-template¶

Prints the remote template used for stack in PATH.

param path

Path to execute the command on.

type path

str

sceptre fetch-remote-template [OPTIONS] PATH

Arguments

PATH¶: Required argument

generate¶

Prints the template used for stack in PATH.

This command is aliased to the dump template command for legacy support reasons. It’s the same as running sceptre dump template.

param no_placeholders

If True, will disable placeholders for unresolvable resolvers. By default, placeholders will be active.

param path

Path to execute the command on.

sceptre generate [OPTIONS] PATH

Options

-n, --no-placeholders¶: If True, no placeholder values will be supplied for resolvers that cannot be resolved.

Arguments

PATH¶: Required argument

launch¶

Launch a Stack or StackGroup for a given config PATH. This command is intended as a catch-all command that will apply any changes from Stack Configs indicated via the path.

* Any Stacks that do not exist will be created * Any stacks that already exist will be updated (if there are any changes) * If any stacks are marked with “ignore: True”, those stacks will neither be created nor updated * If any stacks are marked with “obsolete: True”, those stacks will neither be created nor updated. * Furthermore, if the “-p”/”–prune” flag is used, these stacks will be deleted prior to any

other launch commands

sceptre launch [OPTIONS] PATH

Options

-y, --yes¶: Assume yes to all questions.

-p, --prune¶: If set, will delete all stacks in the command path marked as obsolete.

--disable-rollback, --enable-rollback¶: Disable or enable the cloudformation automatic rollback

Arguments

PATH¶: Required argument

list¶

Commands for listing attributes of stacks.

sceptre list [OPTIONS] COMMAND [ARGS]...

change-sets¶

List change sets for stack.

param path

Path to execute the command on.

type path

str

param url

Write out a console URL instead.

type url

bool

sceptre list change-sets [OPTIONS] PATH

Options

-U, --url¶: Instead write a URL.

Arguments

PATH¶: Required argument

outputs¶

List outputs for stack.

param path

Path to execute the command on.

type path

str

param export

Specify the export formatting.

type export

str

sceptre list outputs [OPTIONS] PATH

Options

-e, --export <export>¶

Specify the export formatting.

Options: envvar | stackoutput | stackoutputexternal

Arguments

PATH¶: Required argument

resources¶

List resources for stack or stack_group.

param path

Path to execute the command on.

type path

str

sceptre list resources [OPTIONS] PATH

Arguments

PATH¶: Required argument

stacks¶

List sceptre stack config attributes,

param path

Path to execute the command on or path to stack group

sceptre list stacks [OPTIONS] PATH

Arguments

PATH¶: Required argument

new¶

Commands for initialising Sceptre projects.

sceptre new [OPTIONS] COMMAND [ARGS]...

group¶

Creates StackGroup folder in the project and a config.yaml with any required properties.

param stack_group

Name of the StackGroup directory to create.

type stack_group

str

sceptre new group [OPTIONS] STACK_GROUP

Arguments

STACK_GROUP¶: Required argument

project¶

Creates PROJECT_NAME project folder and a config.yaml with any required properties.

param project_name

The name of the Sceptre Project to create.

type project_name

str

sceptre new project [OPTIONS] PROJECT_NAME

Arguments

PROJECT_NAME¶: Required argument

prune¶

This command deletes all obsolete stacks in the project. Only obsolete stacks can be deleted via prune; If any non-obsolete stacks depend on obsolete stacks, an error will be raised and this command will fail.

sceptre prune [OPTIONS] [PATH]

Options

-y, --yes¶: Assume yes to all questions.

Arguments

PATH¶: Optional argument

set-policy¶

Sets a specific Stack policy for either a file or using a built-in policy.

param path

Path to execute the command on.

type path

str

param policy_file

path to the AWS Policy file to use.

type policy_file

str

param built_in

the name of the built-in policy file to use.

type built_in

str

sceptre set-policy [OPTIONS] PATH [POLICY_FILE]

Options

-b, --built-in <built_in>¶

Specify a built in stack policy.

Options: deny-all | allow-all

Arguments

PATH¶: Required argument

POLICY_FILE¶: Optional argument

status¶

Prints the stack status or the status of the stacks within a stack_group for a given config PATH.

param path

Path to execute the command on.

type path

str

sceptre status [OPTIONS] PATH

Arguments

PATH¶: Required argument

update¶

Updates a stack for a given config PATH. Or perform an update via change-set when the change-set flag is set.

param path

Path to execute the command on.

type path

str

param change_set

Whether a change set should be created.

type change_set

bool

param verbose

A flag to print a verbose output.

type verbose

bool

param yes

A flag to answer ‘yes’ to all CLI questions.

type yes

bool

sceptre update [OPTIONS] PATH

Options

-c, --change-set¶: Create a change set before updating.

-v, --verbose¶: Display verbose output.

-y, --yes¶: Assume yes to all questions.

--disable-rollback, --enable-rollback¶: Disable or enable the cloudformation automatic rollback

Arguments

PATH¶: Required argument

validate¶

Validates the template used for stack in PATH.

param path

Path to execute the command on.

type path

str

sceptre validate [OPTIONS] PATH

Options

-n, --no-placeholders¶: If True, no placeholder values will be supplied for resolvers that cannot be resolved.

Arguments

PATH¶: Required argument