State Tool for Enterprise

This guide is aimed at our Enterprise Customers who are getting familiar with the ActiveState Platform and want to learn about how to incorporate the State Tool CLI tool into their workflow.

What is the State Tool?

The State Tool is the CLI client that interfaces with the ActiveState Platform. It can be used to install and manage ActiveState runtimes as well as act as a Package Manager that can be used to install packages from our Trusted Artifacts package repository.

Topics

Install the State Tool

You can install the State Tool by running the command below, but it will also be automatically installed when you follow the CLI install instructions for any runtimes that are displayed on the Platform Web UI.

Run this in your Command Prompt (cmd.exe)

powershell -Command "& $([scriptblock]::Create((New-Object Net.WebClient).DownloadString('https://platform.activestate.com/dl/cli/pdli01/install-latest.ps1')))"

sh <(curl -q https://platform.activestate.com/dl/cli/install.sh)

Uninstalling the State Tool

Make sure you shut down all running instances of the State Tool and then run

state clean uninstall

If you run into any issues uninstalling, you can also follow the manual instructions.

Sign in to the ActiveState Platform

As an Enterprise customers, you’ll most likely be working with private projects, meaning that you have to be a member of the organization on the Platform in which they were created. You’ll need to sign in from the CLI.

If you don’t have a Platform account yet, let one of the members of our Customer Success team know and they’ll help you out.

Sign in to the Platform

Run the following command and follow the prompts.

state auth

Installing a Runtime

To install a runtime, you can either find the installation command on the Platform site when you navigate to your project or directly from the command line if you know the project’s name and parent organization.

If you are working with a private project, make sure you authenticate with the State Tool before installing.

Using the installer command from the Web UI

For all projects on the the Platform Web UI, you’ll notice command line instructions like the ones below. Run them in your command line terminal to install the corresponding runtime.

To find a project, first navigate to your organization from platform.activesate.com/organizations, then click on the desired project name. On the next, page, click the Install button to display the instructions.

Sample install project command

What does this installer script do?

  • Downloads & installs the State Tool if it is not already installed on your machine.
  • The State Tool package then downloads & installs the runtime & related artifacts.
  • Sets the language installation as the default on your machine. This means that even when you are not in a virtual environment, it will still be accessible to the rest of your system.
  • Starts a virtual environment for this runtime.

Installing a runtime directly from the command line

If you already have the State Tool installed and you know the project you want to download & install, you can run the command below, replacing the <organization-name> & <project-name> with the ones the correspond to the Platform project you are installing. For personal projects that are not in an organization, use your username where the organization name goes.

Download & install a project

state activate <organization-name>/<project-name>

What does this command do?

  • The State Tool package manager downloads & installs all artifacts for the projectName project
  • Starts a virtual environment for this runtime

Switch between runtimes

The State Tool is designed to help you manage multiple Platform runtimes on the same machine. You can switch between runtimes by “activating” them, which starts up a virtual environment for that runtime.

A virtual environment creates an isolated shell that gives you access to the language & packages in your runtime, but does not affect your system as a whole.

See what runtimes you have installed

state list projects
Start a virtual environment for a runtime

You’ll need to include both the orgnization name and the project name in the command.

state activate orgname/projectname
Start a default environment for a runtime, and make it the system default

When you exit a virtual environment that was activated with -default flag, the installed runtime will still be available to your system.

state activate -default orgname/projectname

Exit an active virtual environmnet

state exit

Install Packages

The State Tool is also a package manager that you can use to install, remove and change versions of packages in your runtime.

Search for avialable packages

state search <package-name>

Install a package

state install <package-name[@version]>

The version specification for this command is optional.

Where do the packages come from?

All packages installed with the State Tool or Platform Web UI come from our own package ecosystem. They have been ingested from various public package repositories and are built from source. If you can’t find a package you are looking for let us know.

Installing packages only modifies your local runtime

When you install or remove packages, your local runtime gets updated but the changes will not be available for others to use until you sync your runtime with the Platform. See the section below on how to do that.

Sync your local runtime with the Platform

When working with a team, you might want to set the changes you are making to your runtime (like when you install new packages) to be availble to the rest of your team. Or, if someone else on your team has made a change, you’ll want to bring your local environment up to date. You can do so with the following commands.

Push your local changes to the Platform

state push

Pull down changes from the Platform

state pull

Did you know all changes are tracked?

The Platform keeps a history of all the changes made to your Project, and you can restore your runtime to any previous configuration.

In the Web UI, navigate to the History tab when browsing your project for more information.

Additional Resources

Get help on the command line

  • To learn more about the State Tool commands, run state --help in the terminal.
  • For help on individual commands, run state COMMAND --help. For example, state install --help.