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
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>
state init jsmith/python3.10 --language firstname.lastname@example.org
Your new project will automatically sync with your Platform account.
After creating your project deploy it locally by checking the project out from the Platform and either
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
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.
activestate.yamlfile to your current working directory, enter
state checkout <orgname>/<projectname>
state checkout exampleorg/Project1 C:\Perl
activestate.yamlfile 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.
activestate.yamlfile directly into your working directory, enter
state checkout <orgname>/<projectname> .
state checkout exampleorg/Project1 C:\Perl .
state shell. This is valuable when using your
activestate.yamlfile for automation.
activestate.yamlfile into the specified location other than your currently working directory, enter
state checkout <orgname>/<projectname> <location>
state checkout exampleorg/Project1 C:\Perl
activestate.yamlfile) anywhere on your system.
.exe, etc.) to a specific location on your system, enter
state checkout <orgname>/<projectname> --runtime-path <location of folder>
state checkout exampleorg/Project1 --runtime-path C:\Perl
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
This will produce a list of all currently checked out projects and their locations on your system.
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
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.
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.
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.
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]>
state install pandas[@1.3.1]
To remove a package from your project enter
state uninstall <packagename[version]>
state uninstall pandas[@1.3.1]
Note that the version specification is optional for both the
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.
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
To view a list of your project’s installed packages enter
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>
state platforms add windowswould 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.
ActiveState supports integration with several integrated development environments. The following environments are supported
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
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.
Now that you have your project set up and the basics configured check out the following sections to learn more about the State Tool: