onflow / flow-cli

The Flow CLI is a command-line interface that provides useful utilities for building Flow applications

Flow CLI brings Flow to your terminal. Easily interact with the network and build your dapps.
Read the docs»

Report Bug · Contribute · Read Guidelines

Installation

To install the Flow CLI, follow the installation instructions on the Flow documentation website.

Documentation

You can find the CLI documentation on the CLI documentation website.

Features

The Flow CLI is a command line tool that allows you to interact with the Flow blockchain. Read about supported commands in the CLI documentation website.

Usage:
  flow [command]

👋 Welcome Flow developer!
   If you are starting a new flow project try running 'flow setup <project_name>'. 

🔥 Super Commands
  dev          Build your Flow project
  flix         Execute FLIX template with a given id, name, or local filename
  generate     Generate new boilerplate files
  setup        Start a new Flow project

📦 Flow Entities
  accounts     Create and retrieve accounts and deploy contracts
  blocks       Retrieve blocks
  collections  Retrieve collections
  events       Retrieve events

💬 Flow Interactions
  scripts      Execute Cadence scripts
  transactions Build, sign, send and retrieve transactions

🔨 Flow Tools
  cadence      Execute Cadence code
  dev-wallet   Run a development wallet
  emulator     Run Flow network for development
  flowser      Run Flowser project explorer
  test         Run Cadence tests

🏄 Flow Project
  deploy       Deploy all project contracts
  init         Initialize a new configuration
  project      Manage your Cadence project
  run          Start emulator and deploy all project contracts

🔒 Flow Security
  keys         Generate and decode Flow keys
  signatures   Signature verification and creation

The Flow CLI includes several commands to interact with Flow networks, such as querying account information, or sending transactions. It also includes the Flow Emulator.

Contributing

Read contributing document.

flow-cli's Issues

Shared library for "scripts execute"

JSON output

Issue To Be Solved

Add the option to print all command outputs as JSON. This makes it easier for other programs to consume structured output from the CLI.

Suggest A Solution

Add a flag to each command that changes the output to JSON. Ideas: --json or --output=json

Report emulator execution errors in cli output

Issue To Be Solved

When using built-in cli commands eg, flow accounts add-contract, the cli reports a successful tx submission, but execution can still fail on the emulator.

(Optional): Suggest A Solution

The cli should not output anything until the emulator has finished, and any emulator messages, especially errors, should be reported in the cli output.

Add an `accounts list`and other helpful accounts commands

Add a command to list details about accounts you created while using the cli.

Issue To Be Solved

After an account is created using the cli, there is no way to recall the account address or keys.
There is no means to introspect accounts in any way without using one of the SDKs.

This would be especially useful for quick debugging in development.

(Optional): Suggest A Solution

• The cli should provide a command to:
  • List Addresses and keys for all accounts
  • A means to introspect accounts and get deployed contracts
  • A means to alias account addresses for easier lookup

Import and deploy contracts from remote sources

Issue To Be Solved

When deploying contracts we currently need to have a copy of that contract locally.

Suggest A Solution

Contract deployment functionality (project deploy) allows us to automatically resolve imports from contracts on the fly and replace them with addresses. These imports are currently relative file locations of the contract source code.

Besides having a relative file location we should allow importing from remote locations (URLs, github repos...). This files should be pulled on the fly and deployed. Another option is that this would first pull the file and save it locally and then deploy it.

This change should also be supported by the language server so it resolves the files.

Shared library for "accounts create"

Improve account management

Issue To Be Solved

It's now common for CLI users to switch between multiple accounts when signing and sending transactions. For example, a project may have both an emulator and testnet account with different keys and addresses.

It's currently possible to use multiple accounts by manually editing flow.json. Does it make sense to move this to a command?

flow signers add <name> <address> ...

Maybe we could automatically save accounts in flow.json after they are created?

flow accounts create --save-as-signer

flow accounts remove

Instructions

Issue To Be Solved

Currently it is not possible to remove a contract via the flow accounts command

(Optional): Suggest A Solution

Implement flow accounts remove

(Optional): Context

https://docs.onflow.org/cadence/language/contracts#removing-a-deployed-contract

Configuration for private accounts in environment variables

Issue To Be Solved

@psiemens wrote:
I think the highest priority is to give users a way to securely specify a few pieces of private data, and that can be solved easily and quickly with environment variable support. Do you think we could implement support for environment variables in this sprint, and then do flow.private.json as a follow-up feature?

I was looking at other examples and it looks like this syntax is quite common:

...
	"accounts": {
		"testnet-account": {
			"address": "f8d6e0586b0a20c7",
			"keys": "${env:MY_PRIVATE_KEY}"
		}
	},
...

A few examples:

https://code.visualstudio.com/docs/editor/variables-reference#_environment-variables
https://www.serverless.com/framework/docs/providers/aws/guide/variables#referencing-environment-variables
https://www.elastic.co/guide/en/beats/winlogbeat/current/using-environ-vars.html

Add support for deploying contracts during account creation

Issue To Be Solved

The CLI used to have a flag for deploying code while creating an account, but it was removed in #1 as part of the update to support multiple contracts per account.

Bring back this functionality and allow specifying zero or more contracts that should be deployed when a contract is created.

Creating keys on Windows 10 produces unusable keys

Problem

While trying to create keys through the CLI they are created but the output is very weird.

Steps to Reproduce

Using Windows 10, in Windows Powershell type flow keys generate

Context

Trying to run kitty-items and this is basically the first step. Here's how the output looks in Windows Terminal:

Contract deployment documentation

We need to ensure that the new functionality introduced in #45 is well documented.

I think it probably makes sense to add documentation in these places:

• The code itself should be documented by following godoc standards
• The command should be well-documented on the CLI help page (e.g. flow projects deploy --help)
• The documentation site should be updated to include examples and usage instructions

Grepable output

Issue To Be Solved

It may be worthwhile to restructure our current command output so that it can be easily parsed by tools such as grep, awk, diff, etc.

Related: https://nmap.org/book/output-formats-grepable-output.html

Questions

Should "grepable" output be the default, or should we prioritize a human readable format? Is it possible for both to be the same? If not, does it make sense to have grepable output as an option, give that we will likely add JSON output?

Testnet faucet integration

Issue To Be Solved

Just an idea at this point, but it'd be convenient if the CLI integrated directly with the Testnet Faucet.

For example:

flow testnet-faucet "Peter Siemens" "[email protected]"

Adjust contract config structure to specify source files for aliases

Issue To Be Solved

The current alias structure works for resolving contract aliases during deployment, but it does not provide a way for code editors (e.g. VS Code) to resolve imports locally and perform semantic checking without reading from the chain.

Suggest A Solution

We can update the flow.json config structure to specify a source file for all contracts. This source file is resolved when developing locally, but is then replaced with the appropriate alias during deployment.

  "contracts": {
    "NonFungibleToken": {
      "source": "./cadence/kittyItems/contracts/NonFungibleToken.cdc",
      "aliases": {
        "testnet": "0xABC"
      }
    },
    "FungibleToken": {
      "source": "./cadence/kittyItems/contracts/FungibleToken.cdc",
      "aliases": {
        "emulator": "0xABC",
        "testnet": "0xABC"
      }
    }
  }

Notify when new version is available for download.

Issue To Be Solved

It's not always easy to know when an upgrade has been released for the CLI. There are a lot of new features planned and it would be great if CLI users were informed about available upgrades as soon as they are available.

(Optional): Suggest A Solution

• CLI can notify users by printing a message in the terminal.
• Message could include platform-specific upgrade instructions

(Optional): Context

We may want to leave the actual upgrade process up to users and specific package managers, instead of having code in the CLI to perform the upgrade.

Query Account Staking Info

Issue To Be Solved

Another common query action is to get staking info. While this is mostly available through using scripts execute, I'm considering adding the ability to get staking/delegation info for the account as a helper, as that seems to be a very common task

Suggest A Solution

Adding a staking-info sub command to accounts, that will query staking/delegation info for the account.

Emulator start fails with default flow.json

Steps to Reproduce

Repro:

1. Run flow project init
2. Run flow emulator start

Observe this error in the terminal:

flow.json contains invalid json: decode private key failed: the signature scheme UNKNOWN is not supported.

Problem

The default flow project init should work with flow emulator start without having to modify the flow.json file.

Context

I found a workaround that may help debug the issue:

1. Run flow emulator start --init
2. Copy the account object generated
3. Delete the generated flow.json file.
4. Run flow project init
5. Replace the generated account under "accounts": { "emulator-account": { ... } with the object generated by flow emulator start --init
6. Rename "emulator-account" fields in the new flow.json to "service" (This is what the emulator expects?)

The emulator starts fine, but when I try flow project deploy I get the following error:

Invalid project configuration: raw private key is not valid

Automated contract deployment

Issue To Be Solved

Currently when using the emulator or testnet, a developer needs to manually redeploy their contracts to apply updates. This is often a tedious process, especially if multiple contracts need to be deployed, or if there is more than one account.

Can the CLI help to automate this process? Ideally a developer would be able to run a simple command to bring the emulator (or testnet) in sync with their local files.

Suggest A Solution

This isn't a concrete solution, but I think we should look into expanding flow.json to include an entry for contracts. I'm not sure what the format would be, but it would allow developers to declare a mapping between accounts and contracts on their local filesystem. The CLI could then detect and redeploy any changes to these files, either automatically or at the user's request.

Transaction arguments

Issue To Be Solved

The CLI doesn't allow the user to pass arguments into a transaction. This prevents the CLI from working with transactions that declare any parameters.

Suggest A Solution

Update the flow transactions send command like this:

flow transactions send --code myTx.cdc --args "foo" 123.2

Project manipulation commands

Issue To Be Solved

Project subset of commands should allow easy usage without manual manipulation of flow.json. Manual manipulation is good for an advance usage but it is prone to typos, errors and more complex to understand without docs.

Suggest A Solution

The current developer flow of using CLI project is:

1. Setup project by running project init
2. Add some contracts to the config
3. Add some accounts to the config
4. Deploy contracts by running project deploy
5. Update contracts by running project deploy --update

Steps 2 and 3 should have a command alternative. Adding accounts should be possible with a command maybe similar to account create --save and contracts should be possible to add with command like project add-contract. Command names are not important right now (they will be further defined with CLI guidelines issue #59 and command refactor).

Store emulator config profiles in flow.json

Issue To Be Solved

If a user wants use multiple configurations for the emulator (with and without fees), they currently have to change CLI flags or environment variables. It would be nice if there was a way to persist the emulator configuration for specific project.

Suggest A Solution

Store emulator config profiles in flow.json, keyed by name.

flow emulator start --config "foo"

Better validation of configuration

There should be a JSON schema validation for configuration properties. We need to validate and provide the best possible feedback to wrong values/properties to users. I think JSON schema can be a good way to achieve this, but it will be different for each format (yaml...). I believe the first step should be improving validation on the abstract configuration structures and second step could be validation of configuration files since the first step provides the feedback the value is not correct but it doesn't say where the value error is located or if the value is missing where that value should be defined.

Add NFT to service acct, list SA contract addresses

Issue To Be Solved

It's unclear what contracts are available pre-installed in the emulator.

(Optional): Suggest A Solution

Working towards batteries included Emulator should come packed with example contracts (TopShot, NFT, Marketplace...etc)
as well as the ability to list out their addresses and any other relevent info in the cli.

Documentation errors

Problem

There are problems with documentation that need fixing as pointed out by the community: https://forum.onflow.org/t/flow-cli-as-a-development-tool/809

Gas estimation tool

Issue To Be Solved

Currently there's no easy way to estimate the gas consumption from a transaction. Developers can adjust the gas limit on the emulator and perform a manual search, but this is tedious.

Can the CLI provide a way to automatically estimate the gas used by a transaction? This likely requires integration with other components (Cadence and/or emulator).

Shared library for CLI command logic

Issue To Be Solved

With the new improvements to flow.json and the flow project command, we want to integrate this functionality into the Flow VS Code extension to provide a more seamless development environment.

To do so, we'd like to explore embedding more functionality into the Cadence language server, implemented here: https://github.com/onflow/cadence

I think it'd be great if we could accomplish this by moving shared functionality into a Go module that can be imported by the language server.

@MaxStalker @sideninja We'll go into more detail in our call later, but here are a few points to start off:

• VS Code should display accounts from flow.json
• VS Code should be able to execute transactions with the same address replacement functionality that is present in flow project deploy
• If the CLI supports loading contracts from remote locations (e.g. URL, git), then the VS Code extension should support this, too.
• The CLI and the VS Code extension should both support transaction/script arguments
• The CLI and the VS Code extension should both support multiple signers per transaction
• the list probably goes on...

Add subset of live network state to Emulator

Issue To Be Solved

Some applications will want to build on top of other applications already deployed on Flow.
This is difficult, given currently there is no way to simulate live network contracts and their state besides manually deploying those contracts on the Emulator, and generating interactions to arrive at the desired starting state.

(Optional): Suggest A Solution

Ability to load a slice of time/block delineated protocol state (Testnet or Mainnet) into the Emulator using a cli command.

Migrate new configuration format to entire CLI

With implementing the functionality described in issue #48 there was a refactor of configuration files and commands. New configuration implementation is structured in two layers.
There are abstract configuration structures and configuration structures that relate to specific configuration type (like json).

We should migrate this configuration to be a single point of truth for CLI for configuration. In order to achieve this we would need to:

• make sure old configuration format is supported (implement a parser for old JSON format and convert it to current configuration)
• replace all config references through-out the CLI and make sure they are calling the new configuration
• make sure all the types match with the new configuration
• account creation should be saved to the new configuration structure and also retrieved
• emulator command should use the new configuration

This migration might also open other questions such as:

• should we have a single initialization for config or not? currently, we have a command flow init and flow project init.

Refactor command structure?

This is more of an idea than anything else, but I'd like to take second look at our command structure and make sure it's the right pattern for us to commit to going forward.

In particular, I'm wondering if it makes sense to flatten the command structure:

flow accounts get

to something like this:

flow get-account

Currently our commands are grouped by entity (e.g. transaction, block, collection) but I'm not sure how well that scales.

For example, which of the two options below is clearer?

flow accounts get
flow blocks get
flow transactions get
flow collections get

flow get-account
flow get-block
flow get-transaction
flow get-collection

Update flow.json schema to include contracts

@sideninja and I have been workshopping a new schema for flow.json that aims to do the following:

• Declare contract source files and deployment targets
• Define aliases for existing contracts
• Multiple network configurations (emulator, testnet, mainnet)
• Multiple account configurations

Additional, @sideninja has been simplifying the format for human readability.

Related discussions: #30 and #45

Configuration for private accounts in separate configuration

Issue To Be Solved

We believe the CLI configuration file flow.json should be included in the versioning control (github...) similar to how for example package.json is.

Since configuration can include sensitive private keys we should allow developers to separate the configuration for their testnet and mainnet accounts from the main flow.json configuration so they are not mistakenly committed to a versioning control systems.

Currently, the configuration looks like this (where secret gets constantly replaced before committing - a ticking bomb):

...
	"accounts": {
		"testnet-account": {
			"address": "f8d6e0586b0a20c7",
			"keys": "SECRET"
		}
	},
...

Suggest A Solution

After a brief discussion with @psiemens we believe there are at least the following solutions to this problems:

Seperate Private Config File

We can create a separate configuration file - let's call it flow.private.json for the sake of the example and this file could include any number of accounts that would on the runtime of CLI command be added to the original flow.json configuration (but not saved to the file). Use of this would happen "in-memory".

Example for flow.private.json:

...
	"accounts": {
		"testnet-account": {
			"address": "f8d6e0586b0a20c7",
			"keys": "ACTUAL_SECRET_WOULD_BE_HERE"
		}
	},
...

And then flow.json could look like:

...
	"accounts": {
                "emulator-account": {
			"address": "f8d6e0586b0a20c7",
			"keys": "11c5dfdeb0ff03a7a73ef39788563b62c89adea67bbb21ab95e5f710bd1d40b7",
			"chain": "flow-emulator"
		},
		"testnet-account": {
                       "private": true
                }
	},
...

Or another option:

...
	"accounts": {
                "emulator-account": {
			"address": "f8d6e0586b0a20c7",
			"keys": "11c5dfdeb0ff03a7a73ef39788563b62c89adea67bbb21ab95e5f710bd1d40b7",
			"chain": "flow-emulator"
		},
		"testnet-account": "flow.private.json"
	},
...

There is also a possibility to not change anything in flow.json and just for the CLI to figure out if the file flow.private.json exists and overwrite it on the fly.

Environment variable support

We could also allow passing account secret as an environment variable. This can be a standalone solution or it can work nicely with the above solution.

Example:

flow project deploy --acount=testnet --secret=123

Example flow.json:

...
	"accounts": {
		"testnet-account": {
			"address": "f8d6e0586b0a20c7",
			"keys": "$ENV.secret"
		}
	},
...

Contract deployment testing

We need to create a unit test suite for the new functionality introduced in #45.

Emulator ran with different config than CLI command

There is an edge case that happens quite a lot where you init the config file, start the emulator, then you go change the config file and you want to run deploy and it doesn't work since signature mismatch. We should detect if config file is not the same as the emulator config file.

CLI design guidelines

Issue To Be Solved

We should update the CONTRIBUTING.md document to include design guidelines for the CLI.

This should includes things like:

• Command structure
• Arguments and flag format
• Documentation standards

Save and share the state of deployed contracts

Issue To Be Solved

When contracts are deployed using the project deploy we get addresses for each deployed contract in the result. These addresses are then used by any transactions or script that interacts with the deployed contracts, but currently, they need to be inserted in imports by hand.

We should have a way to save the addresses of deployed contracts in a state file.

Suggest A Solution

CLI new command for deployment allows us to deploy contracts with a simple command to any desired network. This greatly improves the ability to iterate and update but it would even further improve DevEx if any program could benefit from that work. I'm thinking of a way to save and share the state of deployed contracts.

One way of achieving this would be to have a json file containing newly deployed contracts mapping to their addresses and this file could then be included into any other program. Some kind of a manifest file as @psiemens said.

I think this could be a simple and generic approach that would work among any programming language. Manifests could contain addresses for different networks and potentially maybe even sdk-s could support parsing such a file.

I think we need to open discussion on this topic and get different feedback to create the best solution.

Include complete block results

Issue To Be Solved

Currently the block result printed by the CLI (flow blocks get) is only a partial representation of a complete block. For example, it is missing most of the fields from the block header: https://github.com/onflow/flow-go/blob/master/model/flow/header.go#L16-L27

Suggest A Solution

The CLI should print all block data returned by the Access API. Currently the Access API does not return everything, so it will need to be updated first. After the API is updated, this tool should be updated to print the new data.

The format of the additional data (e.g. block signers) is TBD, but should be consistent with other CLI commands.

Script arguments

Issue To Be Solved

The CLI doesn't allow the user to pass arguments into a script execution. This prevents the CLI from working with scripts that declare any parameters.

Suggest A Solution

Update the flow scripts execute command like this:

flow scripts execute myScript.cdc --args "foo" 123.2

"flow init" fails with JSON error

Problem

flow init fails with the following error:

Failed to save config err: json: error calling MarshalJSON for type *cli.Account: unknown key type 

• This happens in an empty directory with no existing flow.json.

• Reported in v0.12.0, v0.12.1, v0.12.2

Steps to Reproduce

• Install one of the above CLI versions
• Run flow init or flow emulator start --init to see the error message

Acceptance Criteria

flow init and flow emulator start --init should both create a valid flow.json file in the active directory.

Can flow cli autofix issues?

I'm seeing signature-verification-failure issues, vscode provides a way to autofix it but i don't want to go through each file and fix it. How do I do it through the the CLI

Shared library for "transactions send"

Shared library for "accounts add-contract" and "accounts update-contract"

Fund and defund (FLOW) Emulator accounts

Issue To Be Solved

The ability to fund and defund Emulator accounts with FLOW tokens using a cli command

Command autocompletions

Issue To Be Solved

CLI should support autocompletion of commands by using tab key.

Suggest A Solution

Cobra has a good support for this https://github.com/spf13/cobra#generating-shell-completions

Secure key storage

Issue To Be Solved

Private keys are currently stored as plaintext fields in flow.json 👎 👎

While we have support for external signing solutions (e.g. Google KMS), we should still make it more secure to sign locally with the CLI. For example, it's common for developers to use the CLI to interact with testnet.

We should explore options to store private keys securely outside of flow.json.

Suggest A Solution

Ideas that come to mind:

• Add option to load private key from environment variable
• Add option to store private key in local OS keychain (is this possible?)
• Add option to store private key in separate file

Request events for block range

Issue To Be Solved

Currently, it's only possible to get block events for a single block at a time. The access API currently supports getting event info for multiple blocks at once. We should try and leverage this functionality.

Suggest A Solution

We should either:
a) Add the ability to query multiple blocks at once using the current API. (i.e. put under the blocks sub command)

• The advantage here is a large amount of reusable code
• The disadvantage is that we'd actually not use the events API provided by the access API in a very optimized way

b) Add a new subcommand events which would simply query events.

• The advantage would be a cleaner separation of intent, and better use of the AccessAPI,
• The disadvantage would be that we'd now be able to query events from both the blocks and events sub commands, which could be somewhat confusing, as well as still not having the ability to query multiple blocks at once

I am likely to do a PoC of option b) and go from there.

Add support for upgrading contracts on an account

Introduction

Users currently do not have an easy way to update deployed code. It's possible with a custom transaction or through the Go SDK, but ideally it'd be part of the CLI too.

Issue To Be Solved

We would like to add functionality to update code on an existing account. Ideally this works similarly to the accounts create command and also has the option to deploy without re-initializing the contract.

Possible Solution

A flow accounts update-code command that reads from a specified contract file and updates the code of the configured signer.

Example usage:

flow accounts update-code --code MyContract.cdc

Update a contract without re-initializing the contract (using unsafeNotInitializingSetCode):

flow accounts update-code --code MyContract.cdc --no-init

Context

This is potentially blocking us from defining a clear upgrade procedure for testnet contracts.

Deploy contracts with initializer arguments

Issue To Be Solved

The flow projects deploy command should be updated to support init arguments for contracts.

Suggest A Solution

@sideninja actually thought about this use case while designing the new config format.

The idea is to allow for an optional advanced format in the deployments section. Something like this:

"deployments": {
  "emulator": {
    "emulator-account": [
      "NonFungibleToken",
      {
        "name": "Kibble",
        "arguments": ["foo", "42"],
      },
      "KittyItems",
      "KittyItemsMarket"
    ]
  }
}

Context

Brought up by @bjartek on the forum: https://forum.onflow.org/t/flow-cli-as-a-development-tool/809/7?u=pete

Flag to specify location of flow.json

Currently you have to run commands from the directory where the flow.json file is located.
It would be great if users could point to the location using a flag, in situations where it's not ideal to run the command from the same directory as the file.

eg:

flow deploy --config ../../flow.json

Shared library design

Refactor code architecture proposal:

CLI layer

this is where we parse input arguments, do validation of arguments, show errors from the arguments or interpreter, and display human-readable errors we received from the service layer.

CLI layer should implement an interface that has methods:

• validateParameters() - here we do validation of input parameters but only syntax and number etc. - content validity will be checked in service layer
• validateFlags() - here we do validation of flags the same way as in validate parameters
• run() - here we execute the command from the service layer

This layer should have an output module which we use to print. This module will abstract the writer so we can exchange it when testing and check the output. The output will also easily enable writing to file, outputting as JSON, filtering specific data etc.

Service layer

this is where we coordinate complex commands like CommandCreateAccount and create a function for each complex command with custom logic. This layer should return errors but not display anything on the output. This layer should handle the initialization of resources and make network requests. This layer can be stateful. Input parameters must be checked in this layer for validity.

Model layer

this is a stateless layer where we represent data with structures. One such existing example is config (but without saving maybe).