CLI Docs
TIP
To install and configure the Nullstone CLI, visit the setup documentation here.
This document is a cheat sheet and reference for the Nullstone CLI. It contains a list of all the commands along with:
- descriptions
- when to use them
- examples
- options
apply
Runs a Terraform apply on the given block and environment. This is useful for making ad-hoc changes to your infrastructure. This plan will be executed by the Nullstone system. In order to run a plan locally, check out the nullstone workspaces select command. Be sure to run nullstone plan first to see what changes will be made.
Usage
$ nullstone apply [--stack=<stack-name>] --block=<block-name> --env=<env-name> [options]$ nullstone apply [--stack=<stack-name>] --block=<block-name> --env=<env-name> [options]Options
| Option | Description | |
|---|---|---|
--stack | Scope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name. | |
--block | Name of the block to use for this operation | required |
--env | Name of the environment to use for this operation | required |
--wait, -w | Wait for the apply to complete and stream the Terraform logs to the console. | |
--auto-approve | Skip any approvals and apply the changes immediately. This requires proper permissions in the stack. | |
--var | Set variables values for the apply. This can be used to override variables defined in the module. | |
--module-version | The version of the module to apply. |
apps list
Shows a list of the applications that you have access to. Set the --detail flag to show more details about each application.
Usage
$ nullstone apps list$ nullstone apps listOptions
| Option | Description | |
|---|---|---|
--detail, -d | Use this flag to show the details for each application |
blocks list
Shows a list of the blocks for the given stack. Set the --detail flag to show more details about each block.
Usage
$ nullstone blocks list --stack=<stack>$ nullstone blocks list --stack=<stack>Options
| Option | Description | |
|---|---|---|
--stack | Name of the stack to use for this operation | required |
--detail, -d | Use this flag to show more details about each block |
blocks new
Creates a new block with the given name and module. If the module has any connections, you can specify them using the --connection parameter.
Usage
$ nullstone blocks new --name=<name> --stack=<stack> --module=<module> [--connection=<connection>...]$ nullstone blocks new --name=<name> --stack=<stack> --module=<module> [--connection=<connection>...]Options
| Option | Description | |
|---|---|---|
--stack | Name of the stack to use for this operation | required |
--name | Provide a name for this new block | required |
--module | Specify the unique name of the module to use for this block. Example: nullstone/aws-network | required |
--connection | Specify any connections that this block will have to other blocks. Use the connection name as the key, and the connected block name as the value. Example: --connection network=network0 |
configure
Establishes a profile and configures authentication for the CLI to use.
Usage
$ nullstone configure --api-key=<api-key>$ nullstone configure --api-key=<api-key>Options
| Option | Description | |
|---|---|---|
--address | Specify the url for the Nullstone API. | |
--api-key | Configure your personal API key that will be used to authenticate with the Nullstone API. You can generate an API key from your profile page. |
deploy
Deploy a new version of your code for this application. This command works in tandem with the nullstone push command. This command deploys the artifacts that were uploaded during the push command.
Usage
$ nullstone deploy [--stack=<stack-name>] --app=<app-name> --env=<env-name> [options]$ nullstone deploy [--stack=<stack-name>] --app=<app-name> --env=<env-name> [options]Options
| Option | Description | |
|---|---|---|
--stack | Scope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name. | |
--app | Name of the app to use for this operation | |
--env | Name of the environment to use for this operation | |
--version | Provide a label for your deployment. If not provided, it will default to the commit sha of the repo for the current directory. | |
--wait, -w | Wait for the deploy to complete and stream the logs to the console. |
envs list
Shows a list of the environments for the given stack. Set the --detail flag to show more details about each environment.
Usage
$ nullstone envs list --stack=<stack-name>$ nullstone envs list --stack=<stack-name>Options
| Option | Description | |
|---|---|---|
--stack | Name of the stack to use for this operation | required |
--detail, -d | Use this flag to show more details about each environment |
envs new
Creates a new environment in the given stack. If the --preview parameter is set, a preview environment will be created and the --provider parameter will not be used. Otherwise, a standard environment will be created as the last environment in the pipeline. Specify the provider, region, and zone to determine where infrastructure will be provisioned for this environment.
Usage
$ nullstone envs new --name=<name> --stack=<stack> [--provider=<provider>] [--preview]$ nullstone envs new --name=<name> --stack=<stack> [--provider=<provider>] [--preview]Options
| Option | Description | |
|---|---|---|
--name | Provide a name for this new environment | required |
--stack | Name of the stack to use for this operation | required |
--preview | Use this flag to create a preview environment. If not set, a standard environment will be created. | |
--provider | Select the name of the provider to use for this environment. When creating a preview environment, this parameter will not be used. | |
--region | Select which region to launch infrastructure for this environment. Defaults to us-east-1 for AWS and us-east1 for GCP. | |
--zone | For GCP, select the zone to launch infrastructure for this environment. Defaults to us-east1b |
envs delete
Deletes the given environment. Before issuing this command, make sure you have destroyed all infrastructure in the environment. If you are deleting a preview environment, you can use the --force flag to skip the confirmation prompt.
Usage
$ nullstone envs delete --stack=<stack> --env=<env> [--force]$ nullstone envs delete --stack=<stack> --env=<env> [--force]Options
| Option | Description | |
|---|---|---|
--stack | Name of the stack to use for this operation | required |
--env | Name of the environment to use for this operation | required |
--force | Use this flag to skip the confirmation prompt when deleting an environment. |
envs up
Launches an entire environment including all of its apps. This command can be used to stand up an entire preview environment.
Usage
$ nullstone envs up --stack=<stack> --env=<env>$ nullstone envs up --stack=<stack> --env=<env>Options
| Option | Description | |
|---|---|---|
--stack | Name of the stack to use for this operation | required |
--env | Name of the environment to use for this operation | required |
envs down
Destroys all the apps in an environment and all their dependent infrastructure. This command is useful for tearing down preview environments once you are finished with them.
Usage
$ nullstone envs down --stack=<stack> --env=<env>$ nullstone envs down --stack=<stack> --env=<env>Options
| Option | Description | |
|---|---|---|
--stack | Name of the stack to use for this operation | required |
--env | Name of the environment to use for this operation | required |
exec
Executes a command on a container or the virtual machine for the given application. Defaults command to '/bin/sh' which acts as opening a shell to the running container or virtual machine.
Usage
$ nullstone exec [--stack=<stack-name>] --app=<app-name> --env=<env-name> [options] [command]$ nullstone exec [--stack=<stack-name>] --app=<app-name> --env=<env-name> [options] [command]Options
| Option | Description | |
|---|---|---|
--stack | Scope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name. | |
--app | Name of the app to use for this operation | |
--env | Name of the environment to use for this operation | required |
--task | Select a specific task to execute the command against. This is optional and by default will connect to a random task. This is only used by ECS and determines which task to connect. | |
--pod | Select a pod to execute the command against. When specified, allows you to connect to a specific pod within a replica set. This is optional and will connect to a random pod by default. This is only used by Kubernetes clusters and determines which pod in the replica to connect. | |
--container | Select a specific container within a task or pod. If using sidecars, this allows you to connect to other containers besides the primary application container. |
launch
This command will first upload (push) an artifact containing the source for your application. Then it will deploy it to the given environment and tail the logs for the deployment.This command is the same as running nullstone push followed by nullstone deploy -w.
Usage
$ nullstone launch [--stack=<stack-name>] --app=<app-name> --env=<env-name> [options]$ nullstone launch [--stack=<stack-name>] --app=<app-name> --env=<env-name> [options]Options
| Option | Description | |
|---|---|---|
--stack | Scope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name. | |
--app | Name of the app to use for this operation | |
--env | Name of the environment to use for this operation | |
--source | The source artifact to push that contains your application's build. For a container, specify the name of the docker image to push. This follows the same syntax as 'docker push NAME[:TAG]'. For a serverless zip application, specify the .zip archive to push. For a static site, specify the directory to push. | required |
--version | Provide a label for your deployment. If not provided, it will default to the commit sha of the repo for the current directory. |
logs
Streams an application's logs to the console for the given environment. Use the start-time -s and end-time -e flags to only show logs for a given time period. Use the tail flag -t to stream the logs in real time.
Usage
$ nullstone logs [--stack=<stack-name>] --app=<app-name> --env=<env-name> [options]$ nullstone logs [--stack=<stack-name>] --app=<app-name> --env=<env-name> [options]Options
| Option | Description | |
|---|---|---|
--stack | Scope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name. | |
--app | Name of the app to use for this operation | |
--env | Name of the environment to use for this operation | |
--start-time, -s | Emit log events that occur after the specified start-time. This is a golang duration relative to the time the command is issued. Examples: '5s' (5 seconds ago), '1m' (1 minute ago), '24h' (24 hours ago) | |
--end-time, -e | Emit log events that occur before the specified end-time. This is a golang duration relative to the time the command is issued. Examples: '5s' (5 seconds ago), '1m' (1 minute ago), '24h' (24 hours ago) | |
--interval | Set --interval to a golang duration to control how often to pull new log events. This will do nothing unless --tail is set. The default is '1s' (1 second). | |
--tail, -t | Set tail to watch log events and emit as they are reported. Use --interval to control how often to query log events. This is off by default. Unless this option is provided, this command will exit as soon as current log events are emitted. |
modules generate
Generates a nullstone manifest file for your module in the current directory. You will be asked a series of questions in order to collect the information needed to describe a Nullstone module. Optionally, you can also register the module in the Nullstone registry by passing the --register flag.
Usage
$ nullstone modules generate [--register]$ nullstone modules generate [--register]Options
| Option | Description | |
|---|---|---|
--register | Register the module in the Nullstone registry after generating the manifest file. |
modules register
Registers a module in the Nullstone registry. The information in .nullstone/module.yml will be used as the details for the new module.
Usage
$ nullstone modules register$ nullstone modules registermodules publish
Publishes a new version for a module in the Nullstone registry. Provide a specific semver version using the --version parameter.
Usage
$ nullstone modules publish --version=<version>$ nullstone modules publish --version=<version>Options
| Option | Description | |
|---|---|---|
--version, -v | Specify a semver version for the module.'next-patch': Uses a version that bumps the patch component of the latest module version.'next-build': Uses the latest version and appends +build using the short Git commit SHA. (Fails if not in a Git repository) | required |
--include | Specify additional file patterns to package. By default, this command includes *.tf, *.tf.tmpl, and 'README.md'. Use this flag to package additional modules and files needed for applies. This supports file globbing detailed at https://pkg.go.dev/path/filepath#Glob |
modules package
Package all the module contents for a Nullstone module into a tarball but do not publish to the registry.
Usage
$ nullstone modules package$ nullstone modules packageOptions
| Option | Description | |
|---|---|---|
--include | Specify additional file patterns to package. By default, this command includes *.tf, *.tf.tmpl, and 'README.md'. Use this flag to package additional modules and files needed for applies. This supports file globbing detailed at https://pkg.go.dev/path/filepath#Glob |
outputs
Print all the module outputs for a given block and environment. Provide the --sensitive flag to include sensitive outputs in the results. You must have proper permissions in order to use the --sensitive flag. For less information in an easier to read format, use the --plain flag.
Usage
$ nullstone outputs [--stack=<stack-name>] --block=<block-name> --env=<env-name> [options]$ nullstone outputs [--stack=<stack-name>] --block=<block-name> --env=<env-name> [options]Options
| Option | Description | |
|---|---|---|
--stack | Scope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name. | |
--block | Name of the block to use for this operation | required |
--env | Name of the environment to use for this operation | required |
--sensitive | Include sensitive outputs in the results | |
--plain | Print less information about the outputs in a more readable format |
plan
Run a plan for a given block and environment. This will automatically disapprove the plan and is useful for testing what a plan will do.
Usage
$ nullstone plan [--stack=<stack-name>] --block=<block-name> --env=<env-name> [options]$ nullstone plan [--stack=<stack-name>] --block=<block-name> --env=<env-name> [options]Options
| Option | Description | |
|---|---|---|
--stack | Scope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name. | |
--block | Name of the block to use for this operation | required |
--env | Name of the environment to use for this operation | required |
--wait, -w | Wait for the plan to complete and stream the Terraform logs to the console. | |
--var | Set variables values for the plan. This can be used to override variables defined in the module. | |
--module-version | Run a plan with a specific version of the module. |
profile
Usage
$ nullstone profile$ nullstone profilepush
Upload (push) an artifact containing the source for your application. Specify a semver version to associate with the artifact. The version specified can be used in the deploy command to select this artifact.
Usage
$ nullstone push [--stack=<stack-name>] --app=<app-name> --env=<env-name> [options]$ nullstone push [--stack=<stack-name>] --app=<app-name> --env=<env-name> [options]Options
| Option | Description | |
|---|---|---|
--stack | Scope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name. | |
--app | Name of the app to use for this operation | |
--env | Name of the environment to use for this operation | |
--source | The source artifact to push that contains your application's build. For a container, specify the name of the docker image to push. This follows the same syntax as 'docker push NAME[:TAG]'. For a serverless zip application, specify the .zip archive to push. For a static site, specify the directory to push. | required |
--version | Provide a label for your deployment. If not provided, it will default to the commit sha of the repo for the current directory. |
set-org
Most Nullstone CLI commands require a configured nullstone organization to operate. This command will set the organization for the current profile. If you wish to set the organization per command, use the global --org flag instead.
Usage
$ nullstone set-org <org-name>$ nullstone set-org <org-name>ssh
SSH into a running app container or virtual machine. Use the --forward, L option to forward ports from remote service or hosts.
Usage
$ nullstone ssh [--stack=<stack-name>] --app=<app-name> --env=<env-name> [options]$ nullstone ssh [--stack=<stack-name>] --app=<app-name> --env=<env-name> [options]Options
| Option | Description | |
|---|---|---|
--stack | Scope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name. | |
--app | Name of the app to use for this operation | |
--env | Name of the environment to use for this operation | required |
--task | Select a specific task to execute the command against. This is optional and by default will connect to a random task. This is only used by ECS and determines which task to connect. | |
--pod | Select a pod to execute the command against. When specified, allows you to connect to a specific pod within a replica set. This is optional and will connect to a random pod by default. This is only used by Kubernetes clusters and determines which pod in the replica to connect. | |
--container | Select a specific container within a task or pod. If using sidecars, this allows you to connect to other containers besides the primary application container. | |
--forward, -L | Use this to forward ports from host to local machine. Format: local-port:[remote-host]:remote-port |
stacks list
Shows a list of the stacks that you have access to. Set the --detail flag to show more details about each stack.
Usage
$ nullstone stacks list$ nullstone stacks listOptions
| Option | Description | |
|---|---|---|
--detail, -d | Use this flag to show more details about each stack |
stacks new
Creates a new stack with the given name and in the organization configured for the CLI.
Usage
$ nullstone stacks new --name=<name> --description=<description>$ nullstone stacks new --name=<name> --description=<description>Options
| Option | Description | |
|---|---|---|
--name | The name of the stack to create. This name must be unique within the organization. | required |
--description | The description of the stack to create. | required |
status
View the status of your application and whether it is starting up, running, stopped, etc. This command shows the status of an application's tasks as well as the health of the load balancer.
Usage
$ nullstone status [--stack=<stack-name>] --app=<app-name> [--env=<env-name>] [options]$ nullstone status [--stack=<stack-name>] --app=<app-name> [--env=<env-name>] [options]Options
| Option | Description | |
|---|---|---|
--stack | Scope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name. | |
--app | Name of the app to use for this operation | |
--env | Name of the environment to use for this operation | |
--version | Provide a label for your deployment. If not provided, it will default to the commit sha of the repo for the current directory. | |
--watch, -w | Pass this flag in order to watch status updates in real time. Changes will be automatically displayed as they occur. |
up
Launches the infrastructure for the given block/environment and it's dependencies.
Usage
$ nullstone up [--stack=<stack-name>] --block=<block-name> --env=<env-name> [options]$ nullstone up [--stack=<stack-name>] --block=<block-name> --env=<env-name> [options]Options
| Option | Description | |
|---|---|---|
--stack | Scope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name. | |
--block | Name of the block to use for this operation | required |
--env | Name of the environment to use for this operation | required |
--wait, -w | Wait for the launch to complete and stream the Terraform logs to the console. | |
--var | Set variables values for the plan. This can be used to override variables defined in the module. |
version
Prints the version of the CLI.
Usage
nullstone -vnullstone -vworkspaces select
Sync a given workspace's state with the current directory. Running this command will allow you to run terraform plans/applies locally against the selected workspace.
Usage
$ nullstone workspaces select [--stack=<stack>] --block=<block> --env=<env>$ nullstone workspaces select [--stack=<stack>] --block=<block> --env=<env>Options
| Option | Description | |
|---|---|---|
--stack | Scope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name. | |
--block | Name of the block to use for this operation | required |
--env | Name of the environment to use for this operation | required |