Getting started with 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 to install packages from our trusted artifacts package repository.

Setting up the State Tool

Getting started with your project

Other information

Install the State Tool

Open a command prompt and run the following command:

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

Open a command prompt and run the following command:

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

Once installed it is recommended that you close your command prompt and start a new one to ensure your environment is properly updated. While our install process uses PowerShell under the hood, the State Tool does not yet officially support PowerShell (though it has been known to work for various PowerShell use cases).

Uninstalling the State Tool

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

state clean uninstall

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

Sign in to the ActiveState Platform

If you don’t have a Platform account yet, you need to sign up by running

state auth

Enter the requested information at the prompt to register your account. You will receive an email to verify your account. You have limited permissions to the Platform before you verify. After registering your account you can sign in.

If you already have an ActiveState Platform account, or you just created an account you need to sign in by running the same state auth command.

Create a new project locally

You can create a new ActiveState project directly from your command line by running

state init <orgname>/<projectname> --language <language@version>

For example:

state init jsmith/python-3.10 --language python@3.10

Your project will be automatically synced with your Platform account. However, any further changes made to your project using the State Tool (for example adding or removing packages) must be synced using

state push

To pull in changes made to your project via the Platform to your local machine use

state pull

Installing a Runtime

To install a runtime directly from the command line you will need to know the project name and organization. You can install a runtime using the state checkout command.

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

Installing a runtime using state checkout

To checkout a project to your local machine, run

state checkout <orgname>/<projectname>

For example state checkout jsmith/python-3.6

This will create a project folder in your current working directory containing the activestate.yaml file for the project. This file acts as a shortcut to your project, which is stored on your machine. After checking out your project, you can set the runtime as your system default by running

state use <orgname>/<projectname>

or open a temporary virtual environment for the project by running

state shell <orgname>/<projectname>

Installing a runtime using the installer command from the Platform

To find a project, log in to the Platform and go to your organization. Click on the desired project name. Click Install and follow the instructions provided.

Sample install project command

Switching between projects

For a list of projects currently checked out on your local machine, enter

state projects

After finding the desired project on the list shown, switch to a new project by running

state use <orgname>/<projectname>

You can verify that the new runtime is active by running state show.

Add required packages for your project

All packages installed with the State Tool or Platform 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 the package you are looking for let us know.

To add packages to your project using the State Tool enter

state install <package_name>

for example state install pandas. To uninstall a package, enter

state uninstall <package_name>

for example, state uninstall pandas.

For Python projects, if you have a requirements.txt file, you can alternatively import all your packages using the file.

state import requirements.txt

For Perl projects, if you have a cpanfile or META.json file, you can import all your packages using the file.

state import cpanfile

state import META.json

To ensure that the State Tool can successfully find the associated file, store it in the same folder as your project’s activestate.yaml file.

Access documentation for CLI commands

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 packages --help. For more information on the State Tool and the available commands see the State Tool section of the docs.

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.