Working with your project

After creating your project and installing the State Tool, you can get started using your project locally. To access private projects in an organization, the State Tool must be authenticated against the ActiveState Platform by entering

state auth

and following the prompts. Creating an account on the Platform is only necessary to get started with ActiveState. After installing the State Tool, 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/python3.10 --language python@3.10

Your new project will automatically sync with your Platform account.


getting started with your project

installing and removing a package

adding an operating system

Integrating an IDE

updating your project

Getting started with your project

After creating your project deploy it locally by checking the project out from the Platform and either

Checking out your project runtime with state checkout

You can check out more than one runtime at a time, or the same runtime to different locations on your system. A checkout is required before you can use either of the following two commands (state shell and state use).

While the following checkout methods achieve the same goal, downloading your project from the Platform to deploy on your local machine, each has unique qualities to suit different user needs.

  1. To download a project folder containing your project’s activestate.yaml file to your current working directory, enter
state checkout <orgname>/<projectname>
  • For example state checkout exampleorg/Project1 C:\Perl
  • Your activestate.yaml file is entirely owned by the user and acts as a shortcut to your project. The file includes project details such as its location online, language and package information, and security features.
  1. To download your activestate.yaml file directly into your working directory, enter
state checkout <orgname>/<projectname> .
  • For example state checkout exampleorg/Project1 C:\Perl .
  • This method saves having to enter the newly-created project folder in order to open a secure shell using state shell. This is valuable when using your activestate.yaml file for automation.
  1. To download a project folder containing the activestate.yaml file into the specified location other than your currently working directory, enter
state checkout <orgname>/<projectname> <location>
  • For example state checkout exampleorg/Project1 C:\Perl
  • using this method you can use the State Tool to place your project folder (containing your activestate.yaml file) anywhere on your system.
  1. To download your project’s composing files and folders ( .dll, .bat, .exe, etc.) to a specific location on your system, enter
state checkout <orgname>/<projectname> --runtime-path <location of folder>
  • for example state checkout exampleorg/Project1 --runtime-path C:\Perl
  • Using this command will bring the entire installation into the directory specified.
  • This method is useful if you prefer having your project installation in a known location on your machine (e.g. C:\Perl). Or if you need to know the exact path to specific files or folders related to your project.

To find all checked out projects enter the following command

state projects

This will produce a list of all currently checked out projects and their locations on your system.

Deploy a secure shell for your runtime with state shell

After checking out your project, you can launch your runtime in a virtual environment by entering the project folder containing your activestate.yaml file (or any child folder of the project folder) and running

state shell

This will avoid configuring your runtime globally, which could interfere with system tools or other existing projects. Alternatively, entering

state shell <orgname>/<projectname>

into your command line while in any folder other than that containing your project’s activestate.yaml file will start your shell session using that project (provided you previously checked it out from the Platform).

If the same project has been checked out to different locations on your system, you will be prompted to select which project from which location you want to launch your secure environment.

While working with your runtime, entering exit into the command terminal, or closing the application will end your working session in that shell.

Entering a shell environment must be done each time you use your project, either by running the state shell command from the project folder or specifying the project with the state shell <orgname>/<projectname> command. This step can be omitted by setting a project as the default for your system.

Setting your default project runtime with state use

After checking out a project from the Platform, the following command will designate a project runtime as the default for your system. Note you can only have one default.

state use <projectname> 

You can now run the designated project from anywhere on your system, regardless of which working directory you are currently using. To verify that your runtime has been set as the default, enter

state use show 

The output will specify which project, and from which location on your system, your default runtime is currently set.

To change to a new default project enter state use <newprojectname>

You can verify the change by running state use show. To unset your default runtime, enter

state use reset 

to remove that project as the default.

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 activestate.yaml files (and 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]>
  • For example state uninstall pandas[@1.3.1]

Note that the version specification is optional for both the install and uninstall commands. Packages with no version specified will default 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)

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

state packages

See the state import reference documentation for usage information. Check the documentation to find out more about requirement files.

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.

Integrating an IDE

ActiveState supports integration with several integrated development environments. The following environments are supported

Updating your project

Once you’ve installed new packages and made 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

This will create a commit to your project, and produce a “commit ID”. If, at any point, you want to switch back to use your project as it existed when that commit ID was made, enter state switch <commitID>. You can view your commit ID in the History tab of your project page in the Platform.

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


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: