CLI Docs

TIP

To install and configure the Nullstone CLI, visit the setup documentation here.

Cheat sheet and reference for the Nullstone CLI.

This document contains a list of all the commands available in the Nullstone CLI 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

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. When used with --publish, this specifies the version to publish (supports semver, next-patch, and next-build).
--publish	Package and publish the module in the current directory before running the apply. Uses next-build for the version by default, or the value of --module-version if specified.
--if	Only create the run when the condition is met. Supported: any-changes (skip if there are no unapplied workspace changes).

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

Option	Description
--detail, -d	Use this flag to show the details for each application

apps capabilities

Usage

$ nullstone apps capabilities [subcommand]

apps capabilities list

Shows a list of capabilities for the given app. If --env is specified, lists capabilities for the app workspace. Otherwise, lists capabilities from the app's workspace template.

Usage

$ nullstone apps capabilities list --stack=<stack> --app=<app> [--env=<env>]

Options

Option	Description
--stack	Name of the stack to use for this operation	required
--app	Name of the app to use for this operation	required
--env	Name of the environment to use for this operation
--detail, -d	Use this flag to show more details about each capability

apps capabilities create

Adds a capability to an app. If --env is specified, adds the capability to that environment workspace. Otherwise, adds the capability to the app's workspace template.

Usage

$ nullstone apps capabilities create --stack=<stack> --app=<app> [--env=<env>] --module=<module> [--connection=<connection>...]

Options

Option	Description
--stack	Name of the stack to use for this operation	required
--app	Name of the app to use for this operation	required
--env	Name of the environment to use for this operation
--name	Specify the name of the capability to create.	required
--module	Specify the unique name of the module to use for this capability. Example: nullstone/aws-s3-access	required
--connection	Specify any connections that this capability will have to other blocks. Use the connection name as the key, and the connected block name as the value. Example: --connection network=network0

apps capabilities remove

Removes a capability from an app. If --env is specified, removes the capability from that environment workspace. Otherwise, removes the capability from the app's workspace template.

Usage

$ nullstone apps capabilities remove --stack=<stack> --app=<app> [--env=<env>] --name=<capability-name>

Options

Option	Description
--stack	Name of the stack to use for this operation	required
--app	Name of the app to use for this operation	required
--env	Name of the environment to use for this operation
--name	The name of the capability to remove	required

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

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>...]

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
--dns-template	Specify a template for the dns name portion of the subdomain.This is a template that allows you to add "{{ NULLSTONE_ENV }}" and "{{ NULLSTONE_ORG }}" in template.In production, the "{{ NULLSTONE_ENV }}" will be omitted to create a vanity subdomain.Nullstone will interpolate the template to create a subdomain: "dns-name.domain-name".If you want to create a ".nullstone.app" subdomain using an "autogen" or "nullstone-subdomain" module, set this to "{{ random() }}".For a subdomain on your custom domain, set this to something like "api.{{ NULLSTONE_ENV }}".- "dev" env = api.dev.example.com- "prod" env = api.example.com

configure

Establishes a profile and configures authentication for the CLI to use.

Usage

$ 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]

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.
--env-var, -e	Set an additional environment variable on the app for this deployment in the form KEY=VALUE. Can be specified multiple times. Values may reference other --env-var values or standard env vars (e.g. NULLSTONE_VERSION) using {{ VAR }}, but cannot reference secrets. These env vars apply to this deployment only; a subsequent infra run or deploy may overwrite them.
--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. Filters are applied by the API. They can be combined: an environment must satisfy every flag given, and repeating --type widens the match.

Usage

$ nullstone envs list --stack=<stack-name> [--type=<type>] [--tag KEY=VALUE] [--status=<status>] [--prod|--non-prod] [--name=<pattern>]

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
--type	Only show environments of this type: pipeline, preview, previews-shared, or global. Can be specified multiple times to show more than one type.
--tag	Only show environments whose tags match KEY=VALUE. Can be specified multiple times; an environment must match every tag given. An empty value (--tag claim=) matches environments where the tag is unset, absent, or empty, which is how you find environments that haven't been tagged yet.
--status	Only show environments with this status: active (the default) or archived.
--prod	Only show production environments. Cannot be combined with --non-prod.
--non-prod	Only show non-production environments. Cannot be combined with --prod.
--name	Only show environments matching this name, case-insensitively. A pattern containing * or ? is matched against the whole name (--name='pr-*'); anything else matches as a substring.

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

Option	Description
--name	Provide a name for this new environment. If creating a preview environment, we recommend branch`-`pull_request_id.	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
--description	Describe what this environment is for.
--tag	Set a tag on the environment in the form KEY=VALUE. Can be specified multiple times. An empty value (--tag claim=) sets the tag to an empty string, which is not the same as removing it -- use --remove-tag for that.

envs update

Updates an existing environment. Only the attributes you pass are changed; everything else is left alone.

Tags are applied as a per-key patch, so --tag adds or updates a single key and --remove-tag deletes one, both without disturbing the environment's other tags. Setting a tag to an empty value (--tag claim=) keeps the key with an empty value, which is not the same as removing it.

Usage

$ nullstone envs update --stack=<stack> --env=<env> [--name=<name>] [--description=<text>] [--tag KEY=VALUE] [--remove-tag KEY]

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
--name	Rename the environment.
--description	Describe what this environment is for. Pass an empty value to clear it.
--prod	Mark this environment as production. Cannot be combined with --non-prod.
--non-prod	Mark this environment as non-production. Cannot be combined with --prod.
--tag	Set a tag on the environment in the form KEY=VALUE. Can be specified multiple times. An empty value (--tag claim=) sets the tag to an empty string, which is not the same as removing it -- use --remove-tag for that.
--remove-tag	Remove a tag from the environment by key. Can be specified multiple times. Removing a key that isn't set is not an error.

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]

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. This will only build/deploy apps that have auto-deploy enabled.

Usage

$ 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 infrastructure in an environment. This command is useful for tearing down preview environments once you are finished with them.

Usage

$ 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

envs apps

View and modify the apps configured in a preview environment.

In a preview environment an app is "enabled" by being present in the environment's preview app set, so --disabled removes an app from the environment rather than writing a field.

Usage

$ nullstone envs apps [subcommand]

envs apps list

Shows each app configured in the given preview environment, with the repo and the branch or pull request it tracks.

Usage

$ nullstone envs apps list --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 apps set

Updates every app already in the given preview environment that comes from --repo. Use --app to narrow to a single app. Apps from other repos are left untouched, and a --repo that matches nothing in the environment is an error rather than a no-op write.

Usage

$ nullstone envs apps set --stack=<stack> --env=<env> --repo=<owner/name> [--branch=<branch>|--pull-request=<number>|--disabled]

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
--repo	Select every app in this environment that comes from this repo, e.g. --repo=nullstone-io/nullstone	required
--app	Name of the app to use for this operation
--branch	Track this branch. Cannot be combined with --pull-request; setting it clears any pull request.
--disabled	Remove the matched apps from this environment instead of updating them.

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

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
--instance	Select a specific instance to execute the command against. This allows the user to decide which instance to connect. This is optional and by default will connect to a random instance. This is only used for workspaces that use VMs (e.g. Elastic Beanstalk, EC2 Instances, GCP VMs, Azure VMs, etc.).
--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.

iac test

Test the current repository's IaC files against a Nullstone stack.

Usage

$ nullstone iac test --stack=<stack> --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.
--env	Name of the environment to use for this operation	required

iac generate

Generate IaC from a Nullstone stack for apps

Usage

$ nullstone iac --stack=<stack> --env=<env> --app=<app>

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.
--env	Name of the environment to use for this operation	required
--block	Name of the block to use for this operation

iac sync

Sync IaC configuration to a Nullstone environment and optionally trigger infra updates.

Usage

$ nullstone iac sync --stack=<stack> --env=<env> [--auto-plan] [--auto-apply] [--from-git] [--wait[=<dur>]]

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.
--env	Name of the environment to use for this operation	required
--auto-plan	Queue an infra-update Run on each workspace where IaC changes are detected. The Run is left pending approval.
--auto-apply	Auto-approve any infra-update Run created by the sync. Implies --auto-plan.
--from-git	Force the server to fetch IaC files from the connected GitHub repo at the resolved commit SHA. By default the local files (already discovered by this command) are submitted in the request payload.

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

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.
--env-var, -e	Set an additional environment variable on the app for this deployment in the form KEY=VALUE. Can be specified multiple times. Values may reference other --env-var values or standard env vars (e.g. NULLSTONE_VERSION) using {{ VAR }}, but cannot reference secrets. These env vars apply to this deployment only; a subsequent infra run or deploy may overwrite them.

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

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.
--pod	Restrict logs to a single pod by name (Kubernetes only).
--job	Restrict logs to a single Kubernetes job by name (adds job-name=value`` to the selector) or a single ECS task by ID.
--pod-template-hash	Restrict logs to a single ReplicaSet revision (adds pod-template-hash=value`` to the selector).
--task	Restrict logs to a single ECS task by ID.
--deployment	Restrict logs to a single ECS deployment by ID; logs from all tasks under the deployment are included.

mcp-server

Start an MCP (Model Context Protocol) server that exposes Nullstone CLI commands as tools for AI assistants. Communicates over stdio.

Usage

$ nullstone mcp-server

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] [--manifest-only]

Options

Option	Description
--register	Register the module in the Nullstone registry after generating the manifest file.
--manifest-only	Only generate the module manifest file, do not register or generate Terraform.

modules list

Lists the modules owned by the current organization. Intended for module contributors managing their org's registry. To search the entire Nullstone registry (Nullstone-official, community, etc.), use nullstone modules find.

Usage

$ nullstone modules list

Options

Option	Description
--detailed	Use this flag to show detailed information for each module
--name	Filter modules whose name contains this value
--category	Filter modules by category. Known values: app, capability, datastore, ingress, subdomain, domain, cluster, cluster-namespace, network, block
--subcategory	Filter modules by subcategory. Known values — app: container, serverless, static-site, server; capability: ingress, datastores, secrets, sidecars, events, telemetry
--app-type	Filter app modules by app type. Known values: generic, packaged
--provider	Filter modules by provider type. Known values: aws, gcp, azure
--platform	Filter modules by platform
--subplatform	Filter modules by subplatform

modules find

Search the entire Nullstone module registry across Nullstone-official, your org, and community modules. To list modules owned by your organization, use nullstone modules list. When --contributor is not specified, results include Nullstone-official and your organization's modules.

Usage

$ nullstone modules find [--category=<category>] [--subcategory=<subcategory>] [--app-type=<app-type>] [--provider=<provider>] [--platform=<platform>] [--subplatform=<subplatform>] [--name=<name>] [--contributor=<contributor>]... [--format=table|json]

Options

Option	Description
--category	Filter modules by category. Known values: app, capability, datastore, ingress, subdomain, domain, cluster, cluster-namespace, network, block
--subcategory	Filter modules by subcategory. Requires --category. Known values — app: container, serverless, static-site, server; capability: ingress, datastores, secrets, sidecars, events, telemetry
--app-type	Filter app modules by app type. Known values: generic, packaged
--provider	Filter modules by provider type. Known values: aws, gcp, azure
--platform	Filter modules by platform
--subplatform	Filter modules by subplatform. Requires --platform.
--name	Fuzzy match modules by name
--contributor	Filter by contributor. Repeat the flag to include multiple. Allowed values: nullstone-official, my-org, community. Defaults to nullstone-official,my-org.
--format	Output format. One of: table (default), json

modules describe

Fetches metadata for a module and one of its versions. The positional argument accepts [<org>/]<name>[@<version>]. If the organization is omitted, the current organization is used. If a version is specified via @<version>, the --version flag must not also be set. When no version is provided, the latest published version is described.

Usage

$ nullstone modules describe [<org>/]<name>[@<version>] [--version=<version>] [--format=json|pretty]

Options

Option	Description
--version, -v	Module version to describe. Defaults to the latest published version. Cannot be combined with @version`` in the positional argument.
--format	Output format. One of: json (default), pretty

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 [--if=missing]

Options

Option	Description
--if	Only register when the condition is met. Supported: missing (skip when the module already exists).

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> [--if=checksum-changed]

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
--if	Only publish when the condition is met. Supported: checksum-changed (skip when the packaged tarball matches the latest published version).
--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

Options

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. Use the --field flag to emit a single output value suitable for command substitution in scripts.

Usage

$ nullstone outputs [--stack=<stack-name>] --block=<block-name> --env=<env-name> [--field=<expression>] [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
--field	Print a single output value using Terraform-style syntax (e.g. instance_id, endpoint.host, hosts[0], hosts["item1"]). Strings print raw; other values print as compact JSON. Takes precedence over --plain.

Examples

Start an SSM session against an instance using its instance_id output:

$ aws ssm start-session --target $(nullstone outputs --block=<app-name> --env=<env-name> --field=instance_id)

Access nested values with Terraform-style expressions (single-quote the expression so your shell doesn't interpret the brackets):

$ nullstone outputs --block=<app-name> --env=<env-name> --field='hosts[0]'

If the output doesn't exist, the command exits non-zero with a list of available outputs. Sensitive outputs require the --sensitive flag; without it, --field exits non-zero instead of printing a redacted value.

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

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.

preview-apps find

Searches a stack for preview apps matching a repo and pull request. This is used in CI to discover the preview environment created for a pull request without knowing the environment name up front. The results report the stack, environment, and application names, which can be fed into other commands such as nullstone wait and nullstone run. If no preview apps match, this command writes a message to stderr and exits with a non-zero status so CI can branch on the result.

Usage

$ nullstone preview-apps find --stack=<stack-name> --repo=<repo> [--pull-request=<pull-request>] [--format=table|json]

Options

Option	Description
--stack	Name of the stack to use for this operation	required
--repo	Filter preview apps by repository. Accepts either the repo name (e.g. acme/widgets) or the full repo URL.	required
--pull-request	Filter preview apps by pull request. Accepts either the pull request number (e.g. 123) or the Nullstone pull request id.
--format	Output format. One of: table (default), json

profile

Usage

$ nullstone profile

pull

Download (pull) an artifact containing the source for your application. --version is required to identify which artifact to pull.

Usage

$ nullstone pull [--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
--version	Provide a label for your deployment. If not provided, it will default to the commit sha of the repo for the current directory.	required

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. By default, this command does nothing if an artifact with the same version already exists. Use --unique to force push with a unique version.

Usage

$ 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.
--unique	Use this to always push the artifact with a unique version. If the input version already exists, an incrementing -count`` suffix is added.

release

Make your infra and app code live through a single workflow. Nullstone runs an infra-update when there are outstanding workspace changes and a deploy for the resolved app version, picking the optimal, most reliable path.

Usage

$ nullstone release [--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.
--env-var, -e	Set an additional environment variable on the app for this deployment in the form KEY=VALUE. Can be specified multiple times. Values may reference other --env-var values or standard env vars (e.g. NULLSTONE_VERSION) using {{ VAR }}, but cannot reference secrets. These env vars apply to this deployment only; a subsequent infra run or deploy may overwrite them.
--auto-approve	Skip any approvals on the infra-update. This requires proper permissions in the stack.
--wait, -w	Wait for the release to complete and stream the logs to the console.

run

Starts a new container/serverless for the given Nullstone job/task.

Usage

$ nullstone run [--stack=<stack-name>] --app=<app-name> --env=<env-name> [options] [-- command [args...]]

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
--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.
--env-var, -e	Pass environment variables to the job/task. You can use this flag multiple times to specify multiple environment variables. For each environment variable, use NAME=value.This is supported for AWS ECS/Fargate jobs, GCP Cloud Run jobs, and Kubernetes jobs.This is not supported for AWS Lambda; a lambda function's environment variables are configured at deploy time.Use --payload to send input to a lambda function.
--payload	Pass an input event to the function.Use '@filename' to read the payload from a file, or '-' to read the payload from stdin.The payload must be a valid JSON document.This is supported for AWS Lambda functions.

secrets list

Shows a list of secrets in the cloud platform that is configured for the given stack and environment.

Usage

$ nullstone secrets list --stack=<stack-name> --env=<env-name>

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

secrets create

Creates a new secret in the given stack and environment.

Usage

$ nullstone secrets create --stack=<stack-name> --env=<env-name> --name=<secret-name> --value=<secret-value>

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
--name	The name of the secret to create	required
--value	The value of the secret	required

secrets update

Updates an existing secret in the given stack and environment.

Usage

$ nullstone secrets update --stack=<stack-name> --env=<env-name> --name=<secret-name> --value=<secret-value>

Use --value=- to read the secret value from stdin.

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
--name	The name of the secret to update	required
--value	The new value of the secret. Use - to read from stdin.	required

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

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
--instance	Select a specific instance to execute the command against. This allows the user to decide which instance to connect. This is optional and by default will connect to a random instance. This is only used for workspaces that use VMs (e.g. Elastic Beanstalk, EC2 Instances, GCP VMs, Azure VMs, etc.).
--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

Options

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>

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]

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 its dependencies.

Usage

$ 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 -v

wait

Waits for a workspace to reach a specific status. This is helpful to wait for infrastructure to provision or an app to deploy. Currently, this supports --for=launched to wait for a workspace to provision and --for=deployed to wait for an app to deploy successfully. In the future, we will add --for=destroyed.

Usage

$ nullstone wait [--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
--for	Configure the wait command to reach a specific status. Currently this supports --for=launched and --for=deployed. In the future, we will support --for=destroyed
--timeout	Set --timeout to a golang duration to control how long to wait for a status before cancelling. The default is '1h' (1 hour).
--approval-timeout	Set --approval-timeout to a golang duration to control how long to wait for approval before cancelling. If the workspace run never reaches "needs-approval", this has no effect. The default is '15m' (15 minutes).

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

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