Your First Project

After creating your project and installing the State Tool, you can get started using your project locally. This can be done by either

  • checking out your project and launching it in a secure virtual environment (separately), or
  • activating your project using a single command to download and launch a secured virtual environment.

After setting up your project locally and adding your packages, you can then push your local changes to the Platform when it can be accessed by other users.

To access private projects in an organization, the State Tool must be authenticated against the ActiveState Platform. Enter

state auth

And follow the prompts to authenticate your account.

Checking out a project

The State Tool has several different commands to check out your project from the Platform. The same project can be checked out to multiple different locations on your local machine.

  • To checkout your project to your working directory, enter
state checkout <orgname>/<projectname>

This will create a project folder containing your project’s activestate.yaml file in your current working directory.

  • To only download your project’s activestate.yaml file to your working directory, enter
state check out <orgname>/<projectname> . 
  • To check out a project to a specific location on your machine, enter
state checkout <orgname>/<projectname> <location>

This will download the activestate.yaml file into the specified location, for example state checkout exampleorg/Project1 c:/Perl

  • To download all of the bits from your project into a specific location, enter
state check out <orgname>/<projectname> --runtime-path <location of folder>

for example state checkout exampleorg/Project1 --runtime-path c:/Perl

After you have checked out your project, you can launch it in a secure virtual environment by running

state shell <projectname>

If you have the same project checked out in different locations, you will be prompted to select which project in which location you want to launch your secure environment.

Activating your project

Another option to start working with your virtual environment is to activate your project by going to your working directory and running

state activate orgname/projectname 

If you already had this project checked out locally, the State Tool will direct you to the correct local directory. If you had not checked it out locally then State Tool will perform a fresh checkout. See the state activate reference documentation for usage information.

Activate by directory

Change your current working directory to the directory containing your projects’ activestate.yaml , then run

state activate

This will activate the project in your current working directory.


When you are finished working with your project, you can deactivate the runtime environment for your project by entering exit or pressing Ctrl+D to return to your regular shell environment.


When you want to work on your project again you can run the same state activate orgname/projectname command from any directory and you’ll be switched into an activated state under your project directory. Alternatively, you can manually move to the root of your project directory (containing your activestate.yaml file) and simply run state activate .

Install/remove a package

By default, the State Tool operates on a project in your current working directory. Meaning it will look for an activestate.yaml in your current directory or its parent directories and use the project defined in that file.

If an activestate.yaml is not present, running state install <packagename> will create a new one in your current working directory. This is important to note, because if you then run another state install <packagename> command in a different unrelated directory; you will end up with two separate projects.

To install a new package run the following command:

state install <packagename[version]>

For example state install pandas[@1.3.1]

To remove a package from your project enter

state uninstall <packagename[version]>

Note that the version specification is optional for both the install and uninstall commands. Packages with no version specified will be defaulted to the most recent version. See the state install reference documentation for more info.

You can search for specific packages on the Platform using the state search subcommand. See the state search reference documentation for usage information.

Importing multiple packages

If your project already has packages defined for a different package manager then odds are you will be able to import these to the Platform by running:

state import requirements.txt 

Some examples of supported package files:

  • requirements.txt (Python)
  • cpanfile (Perl)
  • META.json (Perl)

See the state import reference documentation for usage information.

To view a list of your project’s installed packages enter

state packages

Adding an operating system

By default the State Tool will use your operating system as the target operating system for your requests. If you would like to target multiple OSs you can add these manually using

state platforms add <operating system>

For example state platforms add Windows would include the Windows operating system to your project. Currently, this feature is only available to paid-tier accounts.

See the state platforms reference documentation for usage information.

Updating your project

Once you’ve installed new packages and made other changes to your project locally, you can save those changes to the Platform. This will allow you to share your virtual environment with other users or different runtime environments (eg. a “staging” or “production” environment).

To save the changes from your local virtual environment to the Platform, enter

state push

Then follow the prompts and instructions. You can now share this runtime with others who will receive your project with all changes made locally included.

See the state push reference documentation for usage information.

What’s Next

Now that you have your project set up and the basics configured check out the following sections to learn more about the State Tool: