Skip to content

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]

Options

OptionDescription
--stackScope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name.
--blockName of the block to use for this operationrequired
--envName of the environment to use for this operationrequired
--wait, -wWait for the apply to complete and stream the Terraform logs to the console.
--auto-approveSkip any approvals and apply the changes immediately. This requires proper permissions in the stack.
--varSet variables values for the apply. This can be used to override variables defined in the module.
--module-versionThe 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

Options

OptionDescription
--detail, -dUse 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>

Options

OptionDescription
--stackName of the stack to use for this operationrequired
--detail, -dUse 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>...]

Options

OptionDescription
--stackName of the stack to use for this operationrequired
--nameProvide a name for this new blockrequired
--moduleSpecify the unique name of the module to use for this block. Example: nullstone/aws-networkrequired
--connectionSpecify 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>

Options

OptionDescription
--addressSpecify the url for the Nullstone API.
--api-keyConfigure 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]

Options

OptionDescription
--stackScope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name.
--appName of the app to use for this operation
--envName of the environment to use for this operation
--versionProvide a label for your deployment. If not provided, it will default to the commit sha of the repo for the current directory.
--wait, -wWait 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>

Options

OptionDescription
--stackName of the stack to use for this operationrequired
--detail, -dUse 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]

Options

OptionDescription
--nameProvide a name for this new environmentrequired
--stackName of the stack to use for this operationrequired
--previewUse this flag to create a preview environment. If not set, a standard environment will be created.
--providerSelect the name of the provider to use for this environment. When creating a preview environment, this parameter will not be used.
--regionSelect which region to launch infrastructure for this environment. Defaults to us-east-1 for AWS and us-east1 for GCP.
--zoneFor GCP, select the zone to launch infrastructure for this environment. Defaults to us-east1b

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>

Options

OptionDescription
--stackName of the stack to use for this operationrequired
--envName of the environment to use for this operationrequired

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>

Options

OptionDescription
--stackName of the stack to use for this operationrequired
--envName of the environment to use for this operationrequired

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]

Options

OptionDescription
--stackScope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name.
--appName of the app to use for this operation
--envName of the environment to use for this operationrequired
--taskSelect a specific task/replica to execute the command against. This is optional and by default will connect to a random task/replica. If using Kubernetes, this will select which replica of the pod to connect. If using ECS, this will select which task of the service to connect.

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]

Options

OptionDescription
--stackScope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name.
--appName of the app to use for this operation
--envName of the environment to use for this operation
--sourceThe 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
--versionProvide 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]

Options

OptionDescription
--stackScope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name.
--appName of the app to use for this operation
--envName of the environment to use for this operation
--start-time, -sEmit 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, -eEmit 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)
--intervalSet --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, -tSet 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]

Options

OptionDescription
--registerRegister 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

modules 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>

Options

OptionDescription
--version, -vSpecify 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
--includeSpecify 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

Options

OptionDescription
--includeSpecify 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]

Options

OptionDescription
--stackScope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name.
--blockName of the block to use for this operationrequired
--envName of the environment to use for this operationrequired
--sensitiveInclude sensitive outputs in the results
--plainPrint 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]

Options

OptionDescription
--stackScope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name.
--blockName of the block to use for this operationrequired
--envName of the environment to use for this operationrequired
--wait, -wWait for the plan to complete and stream the Terraform logs to the console.
--varSet variables values for the plan. This can be used to override variables defined in the module.
--module-versionRun a plan with a specific version of the module.

profile

Usage

$ nullstone profile

push

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]

Options

OptionDescription
--stackScope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name.
--appName of the app to use for this operation
--envName of the environment to use for this operation
--sourceThe 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
--versionProvide 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>

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]

Options

OptionDescription
--stackScope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name.
--appName of the app to use for this operation
--envName of the environment to use for this operationrequired
--taskSelect a specific task/replica to execute the command against. This is optional and by default will connect to a random task/replica. If using Kubernetes, this will select which replica of the pod to connect. If using ECS, this will select which task of the service to connect.
--forward, -LUse 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

Options

OptionDescription
--detail, -dUse 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>

Options

OptionDescription
--nameThe name of the stack to create. This name must be unique within the organization.required
--descriptionThe 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]

Options

OptionDescription
--stackScope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name.
--appName of the app to use for this operation
--envName of the environment to use for this operation
--versionProvide a label for your deployment. If not provided, it will default to the commit sha of the repo for the current directory.
--watch, -wPass 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]

Options

OptionDescription
--stackScope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name.
--blockName of the block to use for this operationrequired
--envName of the environment to use for this operationrequired
--wait, -wWait for the launch to complete and stream the Terraform logs to the console.
--varSet 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 -v

workspaces 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>

Options

OptionDescription
--stackScope this operation to a specific stack. This is only required if there are multiple blocks/apps with the same name.
--blockName of the block to use for this operationrequired
--envName of the environment to use for this operationrequired
CLI Docs has loaded