Scripts allow you to define custom commands that can be executed as part of your workflow. They can be used to perform a variety of tasks, such as building your application, running database migrations, or sending notifications.
Use connectTo in a script to auto-inject database URLs, API keys, etc. as environment variables.
Run scripts with stacktape script:run --scriptName myScript or attach them to hooks.
Script types:
local-script: Runs on your machine (or CI). Good for migrations, builds, seed scripts.local-script-with-bastion-tunneling: Runs locally but tunnels connections to VPC-only resources (e.g., private databases) through a bastion host.bastion-script: Runs remotely on the bastion host inside your VPC.
Scripts can be shell commands or JS/TS/Python files.
Local script
A local script is executed on the same machine where the Stacktape command is run.
- The script must define one of the following properties:
executeCommand,executeScript,executeCommands, orexecuteScripts. - You can use the
connectToproperty to list the resources that your script needs to access. Stacktape will automatically inject the necessary environment variables for connecting to those resources. For more information, see Connecting to resources.
executeCommand
A single terminal command to execute in a separate shell process.
The command runs on the machine executing the Stacktape command. Be aware of potential differences between local and CI environments (e.g., OS, shell). You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.
executeScript
The path to a script file to execute. The script can be written in JavaScript, TypeScript, or Python and runs in a separate process.
The executable is determined by defaults:configure or the system default (node for JS/TS, python for Python). You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.
executeCommands
A list of terminal commands to execute sequentially. Each command runs in a separate shell process.
The commands run on the machine executing the Stacktape command. Be aware of potential differences between environments. You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.
executeScripts
A list of script files to execute sequentially. Each script runs in a separate process.
The script can be written in JavaScript, TypeScript, or Python. The executable is determined by defaults:configure or the system default. You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.
Local script with bastion tunneling
A local script with bastion tunneling is executed in the same way as a regular local script, but connections to the resources listed in the connectTo property are tunneled through a bastion server.
- This provides a secure, encrypted connection to your resources.
- It allows you to connect to resources that do not have a public endpoint and are only accessible within the stack's default VPC, such as a private
relational-databaseorredis-cluster. - The environment variables injected by the
connectToproperty are automatically adjusted to use the tunneled endpoints.
Your stack must have a bastion resource to use this type of script.

Bastion tunneling is supported for the following resource types:
relational-databaseredis-clusterapplication-load-balancerprivate-service(withloadBalancing.typeset toapplication-load-balancer)
Bastion script
A bastion script is executed remotely on a bastion server.
- Logs from the script's execution are streamed in real-time to your local machine.
- This provides a unified way to execute a set of commands from anywhere.
- You can use the
connectToproperty to list the resources that your script needs to access. Stacktape will automatically inject the necessary environment variables for connecting to those resources. For more information, see Connecting to resources.
Connecting to resources
A list of resources the script needs to interact with. Stacktape automatically injects environment variables with connection details for each specified resource.
Environment variable names are in the format STP_[RESOURCE_NAME]_[VARIABLE_NAME] (e.g., STP_MY_DATABASE_CONNECTION_STRING).
Injected Variables by Resource Type:
Bucket:NAME,ARNDynamoDbTable:NAME,ARN,STREAM_ARNMongoDbAtlasCluster:CONNECTION_STRINGRelationalDatabase:CONNECTION_STRING,JDBC_CONNECTION_STRING,HOST,PORT. For Aurora clusters,READER_CONNECTION_STRING,READER_JDBC_CONNECTION_STRING, andREADER_HOSTare also included.RedisCluster:HOST,READER_HOST,PORTEventBus:ARNFunction:ARNBatchJob:JOB_DEFINITION_ARN,STATE_MACHINE_ARNUserAuthPool:ID,CLIENT_ID,ARNSnsTopic:ARN,NAMESqsQueue:ARN,NAME,URLUpstashKafkaTopic:TOPIC_NAME,TOPIC_ID,USERNAME,PASSWORD,TCP_ENDPOINT,REST_URLUpstashRedis:HOST,PORT,PASSWORD,REST_TOKEN,REST_URL,REDIS_URLPrivateService:ADDRESSWebService:URL
If you are using a local-script-with-bastion-tunneling script, connections to the resources listed in the connectTo property are tunneled through a bastion host. This allows you to access resources that are only accessible from within the VPC and increases the security of the connection. For more information, see Local script with bastion tunneling.
How to execute a script
A script can be executed in two ways:
-
Using the
script:runcommand: -
Inside a hook.
Environment variables
A list of environment variables to pass to the script or command.
Values can be:
- A static string, number, or boolean.
- The result of a custom directive.
- A reference to another resource's parameter using the `$ResourceParam` directive.
- A value from a secret using the `$Secret` directive.
Permissions
You can use the assumeRoleOfResource property to grant a script the same AWS permissions as a specific resource.
The name of a deployed resource whose IAM role the script should assume. This grants the script the same permissions as the specified resource.
The resource must be deployed before the script is executed. Stacktape injects temporary AWS credentials as environment variables, which are automatically used by most AWS SDKs and CLIs.
Supported Resource Types:
functionbatch-jobworker-serviceweb-serviceprivate-servicemulti-container-workloadnextjs-webastro-webnuxt-websveltekit-websolidstart-webtanstack-webremix-web
API reference
LocalScriptAPI referencetypeRequired
Type: string "local-script"
properties.executeScript
Execute Script
Type: string
The path to a script file to execute. The script can be written in JavaScript, TypeScript, or Python and runs in a separate process.
The executable is determined by defaults:configure or the system default (node for JS/TS, python for Python). You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.
properties.executeCommand
Execute Command
Type: string
A single terminal command to execute in a separate shell process.
The command runs on the machine executing the Stacktape command. Be aware of potential differences between local and CI environments (e.g., OS, shell). You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.
properties.executeScripts
Execute Scripts
Type: Array of string
A list of script files to execute sequentially. Each script runs in a separate process.
The script can be written in JavaScript, TypeScript, or Python. The executable is determined by defaults:configure or the system default. You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.
properties.executeCommands
Execute Commands
Type: Array of string
A list of terminal commands to execute sequentially. Each command runs in a separate shell process.
The commands run on the machine executing the Stacktape command. Be aware of potential differences between environments. You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.
properties.cwdDefault: The directory where the Stacktape command was executed.
Working Directory
Type: string
The directory where the script or command will be executed.
properties.pipeStdioDefault: true
Pipe Stdio
Type: boolean
If true, pipes the standard input/output (stdio) of the hook process to the main process. This allows you to see logs from your hook and interact with prompts.
properties.connectTo
Connect To
Type: Array of string
A list of resources the script needs to interact with. Stacktape automatically injects environment variables with connection details for each specified resource.
Environment variable names are in the format STP_[RESOURCE_NAME]_[VARIABLE_NAME] (e.g., STP_MY_DATABASE_CONNECTION_STRING).
Injected Variables by Resource Type:
Bucket:NAME,ARNDynamoDbTable:NAME,ARN,STREAM_ARNMongoDbAtlasCluster:CONNECTION_STRINGRelationalDatabase:CONNECTION_STRING,JDBC_CONNECTION_STRING,HOST,PORT. For Aurora clusters,READER_CONNECTION_STRING,READER_JDBC_CONNECTION_STRING, andREADER_HOSTare also included.RedisCluster:HOST,READER_HOST,PORTEventBus:ARNFunction:ARNBatchJob:JOB_DEFINITION_ARN,STATE_MACHINE_ARNUserAuthPool:ID,CLIENT_ID,ARNSnsTopic:ARN,NAMESqsQueue:ARN,NAME,URLUpstashKafkaTopic:TOPIC_NAME,TOPIC_ID,USERNAME,PASSWORD,TCP_ENDPOINT,REST_URLUpstashRedis:HOST,PORT,PASSWORD,REST_TOKEN,REST_URL,REDIS_URLPrivateService:ADDRESSWebService:URL
properties.environment
Environment Variables
Type: Array of EnvironmentVar
A list of environment variables to pass to the script or command.
Values can be:
- A static string, number, or boolean.
- The result of a custom directive.
- A reference to another resource's parameter using the `$ResourceParam` directive.
- A value from a secret using the `$Secret` directive.
properties.assumeRoleOfResource
Assume Role of Resource
Type: string
The name of a deployed resource whose IAM role the script should assume. This grants the script the same permissions as the specified resource.
The resource must be deployed before the script is executed. Stacktape injects temporary AWS credentials as environment variables, which are automatically used by most AWS SDKs and CLIs.
Supported Resource Types:
functionbatch-jobworker-serviceweb-serviceprivate-servicemulti-container-workloadnextjs-webastro-webnuxt-websveltekit-websolidstart-webtanstack-webremix-web
LocalScriptWithBastionTunnelingAPI referencetypeRequired
Type: string "local-script-with-bastion-tunneling"
properties.bastionResource
Bastion Resource Name
Type: string
The name of the bastion resource to use for tunneling to protected resources.
properties.executeScript
Execute Script
Type: string
The path to a script file to execute. The script can be written in JavaScript, TypeScript, or Python and runs in a separate process.
The executable is determined by defaults:configure or the system default (node for JS/TS, python for Python). You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.
properties.executeCommand
Execute Command
Type: string
A single terminal command to execute in a separate shell process.
The command runs on the machine executing the Stacktape command. Be aware of potential differences between local and CI environments (e.g., OS, shell). You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.
properties.executeScripts
Execute Scripts
Type: Array of string
A list of script files to execute sequentially. Each script runs in a separate process.
The script can be written in JavaScript, TypeScript, or Python. The executable is determined by defaults:configure or the system default. You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.
properties.executeCommands
Execute Commands
Type: Array of string
A list of terminal commands to execute sequentially. Each command runs in a separate shell process.
The commands run on the machine executing the Stacktape command. Be aware of potential differences between environments. You can only use one of executeScript, executeScripts, executeCommand, or executeCommands.
properties.cwdDefault: The directory where the Stacktape command was executed.
Working Directory
Type: string
The directory where the script or command will be executed.
properties.pipeStdioDefault: true
Pipe Stdio
Type: boolean
If true, pipes the standard input/output (stdio) of the hook process to the main process. This allows you to see logs from your hook and interact with prompts.
properties.connectTo
Connect To
Type: Array of string
A list of resources the script needs to interact with. Stacktape automatically injects environment variables with connection details for each specified resource.
Environment variable names are in the format STP_[RESOURCE_NAME]_[VARIABLE_NAME] (e.g., STP_MY_DATABASE_CONNECTION_STRING).
Injected Variables by Resource Type:
Bucket:NAME,ARNDynamoDbTable:NAME,ARN,STREAM_ARNMongoDbAtlasCluster:CONNECTION_STRINGRelationalDatabase:CONNECTION_STRING,JDBC_CONNECTION_STRING,HOST,PORT. For Aurora clusters,READER_CONNECTION_STRING,READER_JDBC_CONNECTION_STRING, andREADER_HOSTare also included.RedisCluster:HOST,READER_HOST,PORTEventBus:ARNFunction:ARNBatchJob:JOB_DEFINITION_ARN,STATE_MACHINE_ARNUserAuthPool:ID,CLIENT_ID,ARNSnsTopic:ARN,NAMESqsQueue:ARN,NAME,URLUpstashKafkaTopic:TOPIC_NAME,TOPIC_ID,USERNAME,PASSWORD,TCP_ENDPOINT,REST_URLUpstashRedis:HOST,PORT,PASSWORD,REST_TOKEN,REST_URL,REDIS_URLPrivateService:ADDRESSWebService:URL
properties.environment
Environment Variables
Type: Array of EnvironmentVar
A list of environment variables to pass to the script or command.
Values can be:
- A static string, number, or boolean.
- The result of a custom directive.
- A reference to another resource's parameter using the `$ResourceParam` directive.
- A value from a secret using the `$Secret` directive.
properties.assumeRoleOfResource
Assume Role of Resource
Type: string
The name of a deployed resource whose IAM role the script should assume. This grants the script the same permissions as the specified resource.
The resource must be deployed before the script is executed. Stacktape injects temporary AWS credentials as environment variables, which are automatically used by most AWS SDKs and CLIs.
Supported Resource Types:
functionbatch-jobworker-serviceweb-serviceprivate-servicemulti-container-workloadnextjs-webastro-webnuxt-websveltekit-websolidstart-webtanstack-webremix-web
BastionScriptAPI referencetypeRequired
Type: string "bastion-script"
properties.bastionResource
Bastion Resource Name
Type: string
The name of the bastion resource on which the commands will be executed.
properties.executeCommand
Execute Command
Type: string
A single terminal command to execute on the bastion host. Logs from the execution are streamed to your terminal.
You can use either executeCommand or executeCommands, but not both.
properties.executeCommands
Execute Commands
Type: Array of string
A list of terminal commands to execute sequentially as a script on the bastion host. Logs from the execution are streamed to your terminal.
You can use either executeCommand or executeCommands, but not both.
properties.cwdDefault: /
Working Directory
Type: string
The directory on the bastion host where the command will be executed.
properties.connectTo
Connect To
Type: Array of string
A list of resources the script needs to interact with. Stacktape automatically injects environment variables with connection details for each specified resource.
Environment variable names are in the format STP_[RESOURCE_NAME]_[VARIABLE_NAME] (e.g., STP_MY_DATABASE_CONNECTION_STRING).
Injected Variables by Resource Type:
Bucket:NAME,ARNDynamoDbTable:NAME,ARN,STREAM_ARNMongoDbAtlasCluster:CONNECTION_STRINGRelationalDatabase:CONNECTION_STRING,JDBC_CONNECTION_STRING,HOST,PORT. For Aurora clusters,READER_CONNECTION_STRING,READER_JDBC_CONNECTION_STRING, andREADER_HOSTare also included.RedisCluster:HOST,READER_HOST,PORTEventBus:ARNFunction:ARNBatchJob:JOB_DEFINITION_ARN,STATE_MACHINE_ARNUserAuthPool:ID,CLIENT_ID,ARNSnsTopic:ARN,NAMESqsQueue:ARN,NAME,URLUpstashKafkaTopic:TOPIC_NAME,TOPIC_ID,USERNAME,PASSWORD,TCP_ENDPOINT,REST_URLUpstashRedis:HOST,PORT,PASSWORD,REST_TOKEN,REST_URL,REDIS_URLPrivateService:ADDRESSWebService:URL
properties.environment
Environment Variables
Type: Array of EnvironmentVar
A list of environment variables to pass to the script or command.
Values can be:
- A static string, number, or boolean.
- The result of a custom directive.
- A reference to another resource's parameter using the `$ResourceParam` directive.
- A value from a secret using the `$Secret` directive.
properties.assumeRoleOfResource
Assume Role of Resource
Type: string
The name of a deployed resource whose IAM role the script should assume. This grants the script the same permissions as the specified resource.
The resource must be deployed before the script is executed. Stacktape injects temporary AWS credentials as environment variables, which are automatically used by most AWS SDKs and CLIs.
Supported Resource Types:
functionbatch-jobworker-serviceweb-serviceprivate-servicemulti-container-workloadnextjs-webastro-webnuxt-websveltekit-websolidstart-webtanstack-webremix-web
EnvironmentVarAPI referenceParent:LocalScriptnameRequired
Environment variable name (e.g., DATABASE_URL, API_KEY).
Type: string
valueRequired
Environment variable value. Numbers and booleans are converted to strings.
Type: string or number or boolean