Configuration file

Protostar can be configured with file protostar.toml, which is located in the root of your project. The file uses the TOML format and allows you to specify various options and settings for Protostar.

Here is an example protostar.toml file:

protostar.toml example

[project]
protostar-version = "PROTOSTAR_VERSION"     # required

# Shared Configuration (affects all commands)
lib-path = "lib"                            # install, update, remove
cairo-path = ["lib/cairo-contracts/src"]    # build, test

# Defines contract names. Currently, this section is required by the build command.
[contracts]
main = ["src/feature_a.cairo", "src/feature_b.cairo"]   
proxy = ["src/proxy.cairo"]
account = ["src/account.cairo"]

# Command Arguments Configuration Section
[test]
target = ["src"]

# Command Configuration Profile
[profile.integration.test]
target = ["tests/integration"]
report-slowest-tests = 5

# Shared Configuration Profile
[profile.devnet.project]
gateway-url = "http://127.0.0.1:5050/"
chain-id = 1536727068981429685321

[profile.testnet.project]
network = "testnet"

[project] section

The [project] section of the protostar.toml file allows you to specify global options and settings for your project.

protostar-version

This attribute is defines what Protostar version should be used with your project. It should be set to the latest compatible Protostar version. If you try to use a different version of Protostar with your project, you will receive a warning and you may experience unexpected errors. This attribute should be updated manually.

Shared Configuration

You can specify options that are shared by multiple Protostar commands in the [project] section. For example, the lib-path option is used by the install, update, and remove commands, and cairo-path is used by the build and test commands.

[contracts] section

The [contracts] section allows you to define contract names and the corresponding files that make up each contract. This is useful because it allows you to refer to contracts by name rather than having to specify the full file path each time. You can also combine multiple files into a single contract. Currently, the [contracts] section is required by the protostar build command.

Here is an example of how to define a contract in the [contracts] section:

[contracts]
my_contract = ["src/feature_a.cairo", "src/feature_b.cairo"]   

Command Arguments Configuration Section

The Command Arguments Configuration section of the protostar.toml file allows you to specify arguments for a specific Protostar command.

For example, the following configuration file specifies the target and ignore-broken arguments for the protostar format command:

Configuration File

[format]
target = ["src", "tests"]
ignore-broken = true

You can then run the protostar format command without specifying the target and ignore-broken arguments in the console:

CLI

protostar format

To learn more about the available options and arguments for each Protostar command, refer to the CLI Reference or run protostar COMMAND --help to see the list of supported arguments.

Configuration Profiles

Configuration profiles allow you to easily switch between different Protostar configurations. When you use a profile, it will override the default settings specified in the protostar.toml file with the settings specified in the profile.

To create a configuration profile, add a new section to the protostar.toml. For example:

• to create a Command Configuration named mainnet for the declare-cairo0 command, add [profile.mainnet.declare-cairo0] section
• to create a Shared Configuration named testnet, add [profile.testnet.project] section

To use a profile, add the -p or --profile argument followed by the name of the profile. For example, to use the declare-cairo0 command with the testnet profile, run:

protostar -p testnet declare-cairo0

Migrating from an Older Version of protostar.toml

If you have a protostar.toml file created by an older version of Protostar, you can use the protostar migrate-configuration-file command to update it to the latest format.

This command makes the following changes to your protostar.toml file:

• Removes the protostar prefix from configuration sections
• Changes section names to not be in double quotes
• Merges the ["protostar.config"] and ["protostar.shared_command_configs"] sections into the [project] section
• Changes all keys to use kebab-case instead of snake_case

Here is a table showing the changes between the old and new configuration files:

protostar.toml V1	protostar.toml V2
["protostar.config"]	[project]
["protostar.project"]	[project]
["protostar.shared_command_configs"]	[project]
["protostar.contracts"], ["protostar.build"], ...	[contracts], [build], ...
cairo_path = ..., cairo-path = ...	cairo-path = ...

To migrate your protostar.toml file, run the following command:

protostar migrate-configuration-file