Skip to main content

Command Reference

This is a reference guide to the available commands in the State Tool and how to use them.

Table of Contents​

Environment Setup​

state checkout​

Checkout the given project and setup its runtime

Usage

state checkout [flags] <org/project> <path>

Arguments

  • <org/project> The namespace of the project that you wish to checkout, or the path to a project archive (.tar.gz) to checkout
  • <path> (optional) Where to checkout the project. If not given, the project is checked out to a sub-folder in the current working directory

Flags

  • --branch Defines the branch to checkout
  • --runtime-path Path to store the runtime files
  • --portable Copy files to their runtime path instead of linking to them
  • --no-clone Do not clone the github repository associated with this project (if any)
  • --force, -f Leave a failed project checkout on disk; do not delete it

state commit​

Commit changes to the Build Script

Usage

state commit [flags]

Flags

  • --ts The timestamp at which you want to query. Can be either now (bleeding edge), present (platform present), dynamic (pull in ingredients as needed), or RFC3339 formatted timestamp.
  • --skip-validation, -s Skip validation of the changes. This will allow you to commit even if there are issues resolving the buildscript. This will also skip CVE lookups.

state init​

Initialize a new project

Usage

state init [flags] <org/project> <path>

Arguments

  • <org/project> (optional) The namespace for the project that you wish to initialize. If not in the format of <org/project>, the value will be used as the project name.
  • <path> (optional) Where to initialize the project

Flags

  • --language The Language[@version] that this project should use
  • --private Create a private project

state switch​

Switch to a branch, commit, or tag

Usage

state switch  <identifier>

Arguments

  • <identifier> The commit or branch to switch to

Environment Usage​

state exec​

Intercept and run a script via a project runtime environment

Usage

state exec [flags]

Flags

  • --path The path of the project that you want to use the runtime environment of. If no path is given the current working directory is used.

state refresh​

Updates the given project runtime based on its current configuration

Usage

state refresh  <org/project>

Arguments

  • <org/project> (optional) The namespace of the project to update, or just the project name if previously used

state shell​

Starts a shell/prompt in a virtual environment for the given project runtime

Usage

state shell [flags] <org/project>

Arguments

  • <org/project> (optional) The namespace of the project you wish to start a virtual environment shell/prompt for, or just the project name if previously used

Flags

  • --cd Change to the project directory after starting virtual environment shell/prompt

state use​

Use the given project as your default. This configures it globally in all your shells, and makes State Tool default to it if not other project was found.

Usage

state use  <org/project or project>

Arguments

  • <org/project or project> (optional) The fully qualified namespace (org/project) or just the project name (project) of the project to use. Must have been previously checked out using state checkout.

state use reset​

Stop using your project runtime

Usage

state use reset

state use show​

Show the project runtime you are using

Usage

state use show

state activate​

Activate a project

Usage

state activate [flags] <org/project>

Arguments

  • <org/project> (optional) The namespace of the project that you wish to activate

Flags

  • --path Where to install the project
  • --default Configures the project to always be available for use
  • --branch Defines the branch to be used

Project Usage​

state projects​

List your projects

Usage

state projects

state projects delete (unstable)​

Delete the specified project from the Platform

Usage

state projects delete  <namespace>

Arguments

  • <namespace> org/project

state projects edit (unstable)​

Edit the project details for the specified project

Usage

state projects edit [flags] <namespace>

Arguments

  • <namespace> The namespace of the project to edit

Flags

  • --name Edit the name of the project.
  • --visibility Edit the visibility to non-members, either public or private.
  • --repository Edit the linked VCS repo. To unset use --repo="".

state projects move (unstable)​

Move the specified project to another organization

Usage

state projects move  <org/project> <new-org-name>

Arguments

  • <org/project> The project to move
  • <new-org-name> The organization to move the project to

state projects remote​

List all projects, including ones you have not checked out locally

Usage

state projects remote

state run​

Run your project scripts

Usage

state run  <script>

Arguments

  • <script> Name of script to run

state show (unstable)​

Show information about a project

Usage

state show  <remote>

Arguments

  • <remote> (optional) Namespace of remote project

state artifacts​

Inspect artifacts created for your project

Usage

state artifacts [flags]

Flags

  • --all List all artifacts, including individual package artifacts
  • --namespace The namespace of the project to inspect artifacts for
  • --commit The commit ID to inspect artifacts for
  • --target The target to report artifacts for
  • --full-id List artifacts with their full identifier

state artifacts dl​

Download build artifacts for a given build

Usage

state artifacts dl [flags] <ID> <path>

Arguments

  • <ID> The ID of the artifact to download
  • <path> (optional) The target path to download the artifact to

Flags

  • --namespace The namespace of the project to download artifacts from
  • --commit The commit ID to download artifacts from
  • --target The target to download artifacts from

Package Management​

state bundles (unstable)​

Manage bundles used in your project

Usage

state bundles [flags]

Flags

  • --commit The commit that the listing should be based on
  • --bundle The filter for the bundles names to include in the listing
  • --namespace The namespace bundles should be listed from

state bundles install (unstable)​

Add a new bundle to your project

Usage

state bundles install  <name[@version]>

Arguments

  • <name[@version]> Bundle name and optionally the desired version

state bundles search (unstable)​

Search for all available bundles that can be added to your project

Usage

state bundles search [flags] <name>

Arguments

  • <name> Bundle name

Flags

  • --language The language used to constrain search results
  • --exact-term Ensure that search results match search term exactly

state bundles uninstall (unstable)​

Remove bundle from your project

Usage

state bundles uninstall  <name>

Arguments

  • <name> Bundle name

state import​

Import packages from a list of dependencies

Usage

state import [flags] <File>

Arguments

  • <File> The file to import

Flags

  • --language The language we're importing data from, this determines the format of the import. Leave blank to auto-detect based on filename.
  • --namespace The namespace targeted for the import. Leave blank to auto detect based on filename.
  • --ts The timestamp at which you want to query. Can be either now (bleeding edge), present (platform present), dynamic (pull in ingredients as needed), or RFC3339 formatted timestamp.

state info​

Display information for the specified package

Usage

state info [flags] <name[@version]>

Arguments

  • <name[@version]> Package name and optionally the desired version

Flags

  • --language The language used to constrain package information selection
  • --ts The timestamp at which you want to query. Can be either now (bleeding edge), present (platform present), dynamic (pull in ingredients as needed), or RFC3339 formatted timestamp.

state install​

Add a new package to your project

Usage

state install [flags] <name[@version]>

Arguments

  • <name[@version]> Package name and optionally the desired version. The version may contain wildcards, for example: 1.0.x.

Flags

  • --ts The timestamp at which you want to query. Can be either now (bleeding edge), present (platform present), dynamic (pull in ingredients as needed), or RFC3339 formatted timestamp.

state manifest (unstable)​

List the requirements of the current project

Usage

state manifest [flags]

Flags

  • --expand Expand requirement names to include their namespace

state packages​

List packages used in your project

Usage

state packages [flags]

Flags

  • --commit The commit that the listing should be based on
  • --package The filter for package names to include in the listing
  • --namespace The namespace packages should be listed from

state search (unstable)​

Search for available packages that can be added to your project

Usage

state search [flags] <name>

Arguments

  • <name> Package name, optionally with namespace, eg. [<namespace>/]<name>.

Flags

  • --language The language used to constrain search results
  • --exact-term Ensures that search results match search term exactly
  • --ts The timestamp at which you want to query. Can be either now (bleeding edge), present (platform present), dynamic (pull in ingredients as needed), or RFC3339 formatted timestamp.

state uninstall​

Remove a package from your project

Usage

state uninstall  <name>

Arguments

  • <name> Package name, optionally with namespace, eg. [<namespace>/]<name>.

state upgrade (unstable)​

Upgrade dependencies of a project

Usage

state upgrade [flags]

Flags

  • --ts Manually specify the timestamp to upgrade to. Can be either now or RFC3339 formatted timestamp.
  • --expand Show individual transitive dependency changes rather than a summary

Platform​

state auth​

Authenticate against the ActiveState Platform

Usage

state auth [flags]

Flags

state auth logout​

Logout

Usage

state auth logout

state auth signup​

Signup a new account

Usage

state auth signup

state branch (unstable)​

Manage your project's branches

Usage

state branch

state invite (unstable)​

Invite new members to an organization

Usage

state invite [flags] <email1[,email2,..]>

Arguments

  • <email1[,email2,..]> Email addresses to send the invitations to

Flags

  • --organization Organization to invite to. If not set, invite to current project's organization
  • --role Set user role to member or owner. If not set, prompt for the role

state languages (unstable)​

View the languages of a project

Usage

state languages

state languages install (unstable)​

Update the language of a project

Usage

state languages install  <language>

Arguments

  • <language> The language to update in the form of <language>@<version>

state languages search (unstable)​

Search for an available language to use in your project

Usage

state languages search

state organizations (unstable)​

List member organizations on the ActiveState Platform

Usage

state organizations

state platforms (unstable)​

Manage platforms used in your project

Usage

state platforms

state platforms add (unstable)​

Add a new platform to your project

Usage

state platforms add [flags] <name>

Arguments

  • <name> Name[@<version>]

Flags

  • --bit-width Platform architecture word size/width in bits (32,64)

state platforms remove (unstable)​

Remove a platform from your project

Usage

state platforms remove [flags] <name>

Arguments

  • <name> Name[@<version>]

Flags

  • --bit-width Platform architecture word size/width in bits (32,64)

state platforms search (unstable)​

Search for available platforms that can be added to your project

Usage

state platforms search

state secrets (unstable)​

Manage your secrets

Usage

state secrets [flags]

Flags

  • --filter-usedby Show only secrets that match the given filter. The filter value is the config path that you want to see secrets for, eg. constants.foo, scripts.foo, secrets.project.foo, etc.

state secrets get (unstable)​

Get the value of a secret

Usage

state secrets get  <namespace>

Arguments

  • <namespace> Namespace of secret is SCOPE.NAME. eg. user.mySecret or project.ourSecret

state secrets set (unstable)​

Set the value of a secret

Usage

state secrets set  <namespace> <secret-value>

Arguments

  • <namespace> Namespace of secret is SCOPE.NAME. eg. user.mySecret or project.ourSecret
  • <secret-value> Value of unencrypted Secret

state secrets sync (unstable)​

Synchronize your shareable secrets to everyone in the organization for the current project

Usage

state secrets sync

state security (unstable)​

Show a summary of project vulnerabilities

Usage

state security  <org/project>

Arguments

  • <org/project> (optional) The project for which the report is created

state security open (unstable)​

Open the given vulnerability details in your browser

Usage

state security open  <ID>

Arguments

  • <ID> (optional) The vulnerablility to open in your browser

Author​

state eval​

Evaluate a buildscript target

Usage

state eval  <target>

Arguments

  • <target> The target to evaluate

state publish​

Publish an Ingredient for private consumption.

Usage

state publish [flags] <filepath>

Arguments

  • <filepath> (optional) A tar.gz or zip archive containing the source files of the ingredient.

Flags

  • --edit Create a revision for an existing ingredient, matched by their name and namespace.
  • --editor Edit the ingredient information in your editor before uploading.
  • --name The name of the ingredient. Defaults to basename of filepath.
  • --version Version of the ingredient (preferably semver).
  • --namespace The namespace of the ingredient. Must start with private/<orgname>.
  • --description A short description summarizing what this ingredient is for.
  • --author Ingredient author, in the format of [<name>] <email>. Can be set multiple times.
  • --depend Ingredient that this ingredient depends on. Format as <namespace>/<name>[@<version>]. Can be set multiple times.
  • --depend-runtime Ingredient that this ingredient depends on during runtime. Format as <namespace>/<name>[@<version>]. Can be set multiple times.
  • --depend-build Ingredient that this ingredient depends on during build. Format as <namespace>/<name>[@<version>]. Can be set multiple times.
  • --depend-test Ingredient that this ingredient depends on during tests. Format as <namespace>/<name>[@<version>]. Can be set multiple times.
  • --feature Feature that this ingredient provides. Format as <namespace>/<name>[@<version>]. Can be set multiple times.
  • --meta A yaml file expressing the ingredient meta information. Use --editor to review the file format.

Version Control​

state fork​

Fork an existing ActiveState Platform project

Usage

state fork [flags] <org/project>

Arguments

  • <org/project> The namespace of the project to be forked

Flags

  • --org The organization to fork the project to
  • --name The name of the new project to be created
  • --private Denotes if the forked project will be private

state history​

View history of the active project

Usage

state history

state pull​

Pull in the latest version of your project from the ActiveState Platform

Usage

state pull

state push​

Push your latest changes to the platform

Usage

state push  <org/project>

Arguments

  • <org/project> (optional) The project to push to (uses project under current dir otherwise).

state reset​

Reset local checkout to a particular commit.

Usage

state reset  <CommitID>

Arguments

  • <CommitID> (optional) Reset to the given commit. If not specified, resets local checkout to be equal to the project on the platform

state revert​

Revert a commit

Usage

state revert [flags] <commit-id>

Arguments

  • <commit-id> The commit ID to revert changes from, or HEAD for the latest commit

Flags

  • --to Create a new commit that brings the runtime back to the same state as the commit given

Automation​

state events (unstable)​

Manage project events

Usage

state events

state events log (unstable)​

View a log of events

Usage

state events log [flags]

Flags

  • --follow Don't stop when end of file is reached. Wait for additional data.

state scripts​

Show project scripts

Usage

state scripts

state scripts edit (unstable)​

Edit a given script

Usage

state scripts edit [flags] <name>

Arguments

  • <name> The name of the script to be edited

Flags

  • --expand, -e Whether or not to expand constants within the script

Utilities​

state clean​

Clean caches, configuration files, or completely remove the state tool

Usage

state clean

state clean cache​

Removes cached Runtime Environments

Usage

state clean cache  <org/project>

Arguments

  • <org/project> (optional) The project to be removed from the local cache.

state clean config​

Removes global State Tool configuration. Project configuration will not be affected.

Usage

state clean config

state clean uninstall​

Remove the State Tool, installed languages, and any configuration files

Usage

state clean uninstall [flags]

Flags

  • --all, -a Also delete all associated config and cache files
  • --prompt Asks the user if everything should be deleted or to keep cache and config

state config​

Manage the State Tool configuration

Usage

state config

state config get​

Print config values to the terminal

Usage

state config get  <key>

Arguments

  • <key> Config key

state config set​

Set config values using the terminal

Usage

state config set  <key> <value>

Arguments

  • <key> Config key
  • <value> Config value

state export​

Print information based on the provided subcommand

Usage

state export

state export buildplan (unstable)​

Export the build plan for your project

Usage

state export buildplan [flags]

Flags

  • --namespace The namespace of the project to export the build plan for
  • --commit The commit ID to export the build plan for
  • --target The target to export the build plan for

state export config (unstable)​

Export state tool configurations

Usage

state export config [flags]

Flags

  • --filter Filter configuration output. Accepts: dir

state export env (unstable)​

Export the environment variables associated with your runtime.

Usage

state export env

state export github-actions (unstable)​

Create a github action workflow for your project

Usage

state export github-actions

state export jwt​

Print jwt credentials

Usage

state export jwt

state export log​

Show the path to a State Tool log file

Usage

state export log [flags] <prefix>

Arguments

  • <prefix> (optional) The prefix of the log file to show (e.g. state or state-svc). The default is state

Flags

  • --index, -i The 0-based index of the log file to show, starting with the newest

state export new-api-key​

Create and print new API key

Usage

state export new-api-key  <name>

Arguments

  • <name> API key name

state export private-key​

Exports the private key. This is useful if you want to set it via environment variable (ACTIVESTATE_PRIVATE_KEY)

Usage

state export private-key

state export runtime (unstable)​

Export the runtime associated with your runtime.

Usage

state export runtime  <path>

Arguments

  • <path> (optional) Optional path to your project's runtime if not inside your project

state learn​

Read the State Tool cheat sheet to learn about common commands

Usage

state learn

state update​

Updates the State Tool to the latest available version

Usage

state update [flags]

Flags

  • --set-channel Switches to the given update channel, eg. release.

state update lock​

Lock the State Tool at the current version. This disables automatic updates.

Usage

state update lock [flags]

Flags

  • --set-channel Switches to the given update channel, eg. release.

state update unlock​

Unlock the State Tool version for the current project.

Usage

state update unlock