Skip to main content
Version: Next

Flow CLI Configuration

Flow CLI uses a state called configuration which is stored in a file (usually flow.json).

Flow configuration (flow.json) file will contain the following properties:

  • A networks list pre-populated with the Flow emulator, testnet and mainnet connection configuration.
  • An accounts list pre-populated with the Flow Emulator service account.
  • A deployments empty object where all deployment targets can be defined.
  • A contracts empty object where you define contracts you wish to deploy.

Example Project Configuration​


_15
{
_15
"networks": {
_15
"emulator": "127.0.0.1:3569",
_15
"mainnet": "access.mainnet.nodes.onflow.org:9000",
_15
"testnet": "access.devnet.nodes.onflow.org:9000"
_15
},
_15
"accounts": {
_15
"emulator-account": {
_15
"address": "f8d6e0586b0a20c7",
_15
"key": "ae1b44c0f5e8f6992ef2348898a35e50a8b0b9684000da8b1dade1b3bcd6ebee",
_15
}
_15
},
_15
"deployments": {},
_15
"contracts": {}
_15
}

Configuration​

Below is an example of a configuration file for a complete Flow project. We'll walk through each property one by one.


_55
{
_55
"contracts": {
_55
"NonFungibleToken": "./cadence/contracts/NonFungibleToken.cdc",
_55
"Kibble": "./cadence/contracts/Kibble.cdc",
_55
"KittyItems": "./cadence/contracts/KittyItems.cdc",
_55
"KittyItemsMarket": "./cadence/contracts/KittyItemsMarket.cdc",
_55
"FungibleToken": {
_55
"source": "./cadence/contracts/FungibleToken.cdc",
_55
"aliases": {
_55
"testnet": "9a0766d93b6608b7",
_55
"emulator": "ee82856bf20e2aa6"
_55
}
_55
}
_55
},
_55
_55
"deployments": {
_55
"testnet": {
_55
"admin-account": ["NonFungibleToken"],
_55
"user-account": ["Kibble", "KittyItems", "KittyItemsMarket"]
_55
},
_55
"emulator": {
_55
"emulator-account": [
_55
"NonFungibleToken",
_55
"Kibble",
_55
"KittyItems",
_55
"KittyItemsMarket"
_55
]
_55
}
_55
},
_55
_55
"accounts": {
_55
"admin-account": {
_55
"address": "3ae53cb6e3f42a79",
_55
"key": "12332967fd2bd75234ae9037dd4694c1f00baad63a10c35172bf65fbb8ad1111"
_55
},
_55
"user-account": {
_55
"address": "e2a8b7f23e8b548f",
_55
"key": "22232967fd2bd75234ae9037dd4694c1f00baad63a10c35172bf65fbb8ad1111"
_55
},
_55
"emulator-account": {
_55
"address": "f8d6e0586b0a20c7",
_55
"key": "2eae2f31cb5b756151fa11d82949c634b8f28796a711d7eb1e52cc301ed11111",
_55
}
_55
},
_55
_55
"networks": {
_55
"emulator": "127.0.0.1:3569",
_55
"mainnet": "access.mainnet.nodes.onflow.org:9000",
_55
"testnet": "access.devnet.nodes.onflow.org:9000",
_55
"testnetSecure": {
_55
"Host": "access-001.devnet30.nodes.onflow.org:9001",
_55
"NetworkKey": "ba69f7d2e82b9edf25b103c195cd371cf0cc047ef8884a9bbe331e62982d46daeebf836f7445a2ac16741013b192959d8ad26998aff12f2adc67a99e1eb2988d"
_55
}
_55
}
_55
}

Contracts​

Contracts are specified as key-value pairs, where the key is the contract name, and the value is the location of the Cadence source code.

The advanced format allows us to specify aliases for each network.

Simple Format​


_10
...
_10
_10
"contracts": {
_10
"NonFungibleToken": "./cadence/contracts/NonFungibleToken.cdc"
_10
}
_10
_10
...

Advanced Format​

Using advanced format we can define aliases. Aliases define an address where the contract is already deployed for that specific network. In the example scenario below the contract FungibleToken would be imported from the address 9a0766d93b6608b7 when deploying to testnet network and address ee82856bf20e2aa6 when deploying to the Flow emulator. We can specify aliases for each network we have defined. When deploying to testnet it is always a good idea to specify aliases for all the common contracts that have already been deployed to the testnet.

⚠️ If we use an alias for the contract we should not specify it in the deployment section for that network.

Our example below should not include FungibleToken in deployment section for testnet and emulator network.


_10
...
_10
"FungibleToken": {
_10
"source": "./cadence/contracts/FungibleToken.cdc",
_10
"aliases": {
_10
"testnet": "9a0766d93b6608b7",
_10
"emulator": "ee82856bf20e2aa6"
_10
}
_10
}
_10
...

Format used to specify advanced contracts is:


_10
"CONTRACT NAME": {
_10
"source": "CONTRACT SOURCE FILE LOCATION",
_10
"aliases": {
_10
"NETWORK NAME": "ADDRESS ON SPECIFIED NETWORK WITH DEPLOYED CONTRACT"
_10
...
_10
}
_10
}

Accounts​

The accounts section is used to define account properties such as keys and addresses. Each account must include a name, which is then referenced throughout the configuration file.

Simple Format​

When using the simple format, simply specify the address for the account, and a single hex-encoded private key.


_10
...
_10
_10
"accounts": {
_10
"admin-account": {
_10
"address": "3ae53cb6e3f42a79",
_10
"key": "12332967fd2bd75234ae9037dd4694c1f00baad63a10c35172bf65fbb8ad1111"
_10
}
_10
}
_10
_10
...

Advanced format​

The advanced format allows us to define more properties for the account. We can define the signature algorithm and hashing algorithm, as well as custom key formats.

Please note that we can use service for address in case the account is used on emulator network as this is a special value that is defined on the run time to the default service address on the emulator network.

Example for advanced hex format:


_16
...
_16
_16
"accounts": {
_16
"admin-account": {
_16
"address": "service",
_16
"key":{
_16
"type": "hex",
_16
"index": 0,
_16
"signatureAlgorithm": "ECDSA_P256",
_16
"hashAlgorithm": "SHA3_256",
_16
"privateKey": "12332967fd2bd75234ae9037dd4694c1f00baad63a10c35172bf65fbb8ad1111"
_16
}
_16
}
_16
}
_16
_16
...

You can also use BIP44 to derive keys from a mnemonic. For more details please see the FLIP

Example for BIP44 format:


_17
...
_17
_17
"accounts": {
_17
"admin-account": {
_17
"address": "service",
_17
"key":{
_17
"type": "bip44",
_17
"index": 0,
_17
"signatureAlgorithm": "ECDSA_P256",
_17
"hashAlgorithm": "SHA3_256",
_17
"mnemonic": "skull design wagon top faith actor valley crystal subject volcano access join",
_17
"derivationPath": "m/44'/539'/0'/0/0"
_17
}
_17
}
_17
}
_17
_17
...

Note: Default value for derivationPath is m/44'/539'/0'/0/0 if omitted.

You can also use a key management system (KMS) to sign the transactions. Currently, we only support Google KMS.

Example for Google KMS format:


_14
...
_14
"accounts": {
_14
"admin-account": {
_14
"address": "service",
_14
"key": {
_14
"type": "google-kms",
_14
"index": 0,
_14
"signatureAlgorithm": "ECDSA_P256",
_14
"hashAlgorithm": "SHA3_256",
_14
"resourceID": "projects/flow/locations/us/keyRings/foo/bar/cryptoKeyVersions/1"
_14
}
_14
}
_14
}
_14
...

You can store the account key to a separate file and provide the file location as part of the key configuration.

Example for separate key file:


_11
...
_11
"accounts": {
_11
"admin-account": {
_11
"address": "service",
_11
"key": {
_11
"type": "file",
_11
"location": "./test.key"
_11
}
_11
}
_11
}
_11
...

Inside the test.key file you should only put the hex key content (e.g. 12332967fd2bd75234ae9037dd4694c1f00baad63a10c35172bf65fbb8ad1111)

Deployments​

The deployments section defines where the project deploy command will deploy specified contracts. This configuration property acts as the glue that ties together accounts, contracts and networks, all of which are referenced by name.

In the deployments section we specify the network, account name and list of contracts to be deployed to that account.

Format specifying the deployment is:


_10
...
_10
"deployments": {
_10
"NETWORK": {
_10
"ACCOUNT NAME": ["CONTRACT NAME"]
_10
}
_10
}
_10
_10
...


_22
...
_22
_22
"deployments": {
_22
"emulator": {
_22
"emulator-account": [
_22
"NonFungibleToken",
_22
"Kibble",
_22
"KittyItems",
_22
"KittyItemsMarket"
_22
]
_22
},
_22
"testnet": {
_22
"admin-account": ["NonFungibleToken"],
_22
"user-account": [
_22
"Kibble",
_22
"KittyItems",
_22
"KittyItemsMarket"
_22
]
_22
}
_22
}
_22
_22
...

Networks​

Use this section to define networks and connection parameters for that specific network.

Format for networks is:


_10
...
_10
"networks": {
_10
"NETWORK NAME": "ADDRESS"
_10
}
_10
...


_10
...
_10
"networks": {
_10
"NETWORK NAME": {
_10
"host": "ADDRESS",
_10
"key": "ACCESS NODE NETWORK KEY"
_10
}
_10
}
_10
...


_13
...
_13
_13
"networks": {
_13
"emulator": "127.0.0.1:3569",
_13
"mainnet": "access.mainnet.nodes.onflow.org:9000",
_13
"testnet": "access.devnet.nodes.onflow.org:9000",
_13
"testnetSecure": {
_13
"host": "access-001.devnet30.nodes.onflow.org:9001",
_13
"key": "ba69f7d2e82b9edf25b103c195cd371cf0cc047ef8884a9bbe331e62982d46daeebf836f7445a2ac16741013b192959d8ad26998aff12f2adc67a99e1eb2988d"
_13
},
_13
}
_13
_13
...

Emulators​

The default emulator CLI is automatically configured with name being "default" and values of serviceAccount: "emulator-account" and port: "3569". The default emulator configuration will not show up on flow.json.

To customize emulator values, add emulator section like the example below:


_10
...
_10
_10
"emulators": {
_10
"custom-emulator": {
_10
"port": 3600,
_10
"serviceAccount": "emulator-account"
_10
}
_10
}
_10
_10
...