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>
state init jsmith/python3.10 --language python@3.10Your new project will automatically sync with your Platform account.
getting started with your project
installing and removing a package
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 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.
activestate.yaml file to your current working directory, enterstate checkout <orgname>/<projectname>
state checkout exampleorg/Project1 C:\Perlactivestate.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.activestate.yaml file directly into your working directory, enterstate checkout <orgname>/<projectname> .
state checkout exampleorg/Project1 C:\Perl .state shell. This is valuable when using your activestate.yaml file for automation.activestate.yaml file into the specified location other than your currently working directory, enterstate checkout <orgname>/<projectname> <location>
state checkout exampleorg/Project1 C:\Perlactivestate.yaml file) anywhere on your system..dll, .bat, .exe, etc.) to a specific location on your system, enterstate checkout <orgname>/<projectname> --runtime-path <location of folder>
state checkout exampleorg/Project1 --runtime-path C:\PerlC:\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.
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.
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.
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]>
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 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.
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.
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 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.
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
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.
Now that you have your project set up and the basics configured check out the following sections to learn more about the State Tool: