Configuration Reference

project: "" constants:   - name: LOCATION     value: world     if: eq .OS.Name "Linux" # optional   - name: DBHOST     value: $secrets.user.dbhost scripts:   - name: hello-world     language: bash     standalone: true # optional     if: eq .OS.Name "Linux" # optional     value: echo $constants.LOCATION   - name: hello-python     language: python3     value: |         import sys         print(sys.executable) events:     - name: activate       if: eq .Shell "bash" # optional       value: echo "Welcome to your activated environment!"     - name: before-command       scope: [ "command-name" ]       value: hello-world     - name: after-command       scope: [ "command-name" ]       value: hello-world     - name: file-changed       scope: [ "folder1", "folder2" ]       value: hello-world


Specifies the full URL to your project on the ActiveState Platform.

The parameters in this URL are automatically updated as you work with your project, but you are also able to manually update them. For example you could change the commitID to an earlier commit to have State tool operate on that commit.


Constants can be used both as variables inside your activestate.yaml as well as to set up environment variables for your activated environments.

You can use the constants you define in other constants, scripts, events, and other configuration fields. The following example defines the same LOCATION constant, and references it in the subsequent entry as $constants.LOCATION. Constants are referenced this way wherever you use them in your activestate.yaml file. Constant names are not case-sensitive.

  - name: LOCATION
    value: World
  - name: HELLO
    value: Hello $constants.LOCATION

Using configuration values as variables is supported for many different fields, not just constants. You can also wrap your variables in brackets in case you’re using them in more advanced scenarios where the variable parser might otherwise get confused, so for example you could use your constant in the following way:

  - name: LOCATION
    value: World
  - name: HELLO
    value: Hello ${constants.LOCATION}

Constants automatically become environment variables. So when you state activate with the above example you will be able to see the LOCATION variable under printenv | grep LOCATION


Scripts allow you to specify your own scripts that will run within the context of your activated environment.


The script name you specify can be accessed in a variety of ways:

  • via state run <script-name>
  • simply by invoking <script-name> as a command when you’re in an activated environment
  • inside your activestate.yaml by using the ${script.<name>} variable


The language specifies one of the Supported Languages.

Note when using a non-shell language your project must have this language specified as a dependency or the script will fail to run.


If specified the script won’t source your runtime environment before being ran.


The value is simply the contents of your script, in whatever language you specified.

Note you can still reference activestate.yaml variables. You can also pass arguments to your script and access them in whichever way your language of choice uses arguments (eg. os.Args).


Events allow you to specify custom functionality based on certain events within the state tool or your environment.


The activate event triggers when you activate or source your runtime environment. The contents of the activate event will be evaluated as part of your shell’s RC file (provided your shell supports RC files), allowing you to set up parts of your shell for the use of your project.

This means that the contents of the activate event are shell specific so you may want to use conditionals to create different activate events per shell, eg.

  - name: activate
    if: ne .Shell "cmd"
    value: export MYVAR=foo
  - name: activate
    if: eq .Shell "cmd"
    value: set MYVAR=foo

before-command & after-command

These events are triggered before and after a command is ran.


The scope contains the list of State Tool commands that this event should trigger on.

To see all available commands run state --help.

For example if you would like to trigger the event before each state install you would use scope: [ "install" ].


The value holds the name of a script that should run when the event is triggered.


Note - the file-changed event is at an experimental stage and may still change or contain bugs.

The file-changed event is triggered as the name suggests; when a file is changed. If specified these events will only trigger while you are in an activated state (ie. you ran state activate).

While in an activated state you can view the logs for file events with state events log.


The scope specifies which folders to watch for file-events on.


The value holds the name of a script that should run when a file has changed.



Most things specified in the activestate.yaml can be accessed throughout as variables. Their structure mimicking their position in the yaml. These variables are formatted either as $variableName or ${variableName}. eg. ${scripts.myScriptName}.

For some usage examples see the Constants section.


You can access a secret via the $secrets.user.<name> or $secrets.project.<name> variables, depending on whether the secret you want is user or project focussed.

Secrets do not have to exist for you to invoke them as merely invoking them will create them.

They also do not need to hold a value before you start using them, if no value exists you will be prompted for it at the time that the secret is used.

Find out more about secrets and their use-cases.

Supported Languages

In places where you can reference the shell the following values are accepted:

bashUses your system bash (Bourne again shell).
shUses your system sh (Bourne shell).
batchUses your system cmd.exe on Windows.
perlUses your projects Perl runtime environment (if configured).
python2Uses your projects Python 2 runtime environment (if configured).
python3Uses your projects Python 3 runtime environment (if configured).


Note - conditionals are still at an experimental stage and may still change or contain bugs.

You can optionally specify conditionals for certain entities. These conditionals use Golang templating, for information on how to write your conditionals see the relevant Golang documentation.

Aside from the built-in Golang tempalte functions conditionals can make use of the following additional functions:

  • .Contains: if: .Contains "Hello World" "World"
  • .HasPrefix: if: .HasPrefix "Hello World" "Hel"
  • .HasSuffix: if: .HasPrefix "Hello World" "rld"
  • .MatchRx: if: .MatchRx "\w+" "Hello"

In addition to functions you can also access the following data:

  • .Project.NamespacePrefix: the namespace of a project (eg. yourUsername/yourProject)
  • .Project.Name: the project name
  • .Project.Owner: the project owner (eg. your username)
  • .OS.Name: OS name (one of Linux, Windows, MacOS, Unknown)
  • .OS.Version: OS version
  • .OS.Architecture: OS architecture (one of i386, x86_64, ARM, unknown)
  • .Shell: The current shell name (one of the Supported Languages)
  • .Mixin.User.Name: Your username (if authenticated)
  • .Mixin.User.Email: Your email (if authenticated)