Adding Corda Node CLI commands

Use this guide to learn about commands in the Corda Node CLI and how you can add new ones.

Download either the Corda Node CLI’s .tar or .zip file.

Existing Corda Node CLI commands

Commands implemented in the Corda Node CLI are endpoint, flow, and vault. Each of these commands can have one or more subcommands, and each subcommand can have further subcommands.

Use the --help option to see the complete list of commands:

java -jar corda-node-cli.jar --help

Usage:

corda [-hvV] [--logging-level=<loggingLevel>] [COMMAND]

Description:


Options:

  -h, --help      Shows this help message and exit.
      --logging-level=<loggingLevel>
                  Enable logging at this level and higher. Possible values:
                    ERROR, WARN, INFO, DEBUG, TRACE
  -v, --verbose, --log-to-console
                  If set, prints logging to the console as well as to a file.
  -V, --version   Print version information and exit.

Commands:

  endpoint  Performs operations on HTTP-RPC endpoints. HTTP-RPC endpoints
              should be created first before any subsequent commands executed
              on them.
  flow      Allows you to start and kill flows, list the ones available and to
              watch flows currently running on the node.
  vault     Allows you to query Corda node's vault and retrieve various types of
              persistent objects from it.

To learn more about how to use each of the commands (and subcommands), use the --help option:

java -jar corda-node-cli.jar endpoint add --help

Usage:

corda endpoint add [-hvV] [--logging-level=<loggingLevel>] [-n=<name>]
                   [[[--basic-auth] -u=<username> -P[=<password>]] |
                   [--azure-ad]] <url>

Description:

Allows to add HTTP-RPC endpoint of the Corda with necessary credentials to the
local cache. After endpoint is added other commands can be executed against it.

Parameters:

      <url>           HTTP-RPC endpoint URL in the form: https://<host>:
                        port/api/v1

Options:

  -h, --help          Shows this help message and exit.
      --logging-level=<loggingLevel>
                      Enable logging at this level and higher. Possible values:
                        ERROR, WARN, INFO, DEBUG, TRACE
  -n, --name=<name>   Human readable name which will be used to identify HTTP
                        RPC endpoint
  -v, --verbose, --log-to-console
                      If set, prints logging to the console as well as to a
                        file.
  -V, --version       Print version information and exit.
Username/password authentication      --basic-auth
  -P, --password[=<password>]
                      Password for password based authentication.
                      If present without value, the password can be entered
                        interactively.
  -u, --username=<username>
                      Username for password based authentication.
AzureAD authentication      --azure-ad

Add new commands to the Corda Node CLI

To add a new command:

  1. Define your new command as a child class of ParentCommand and as a subcommand of CordaCommand, specify your command’s subcommands, and annotate all commands and subcommands with @CommandLine.Command.
  2. Implement business logic in the execute method of each subcommand and override validate in ValidatedCommand (if required).
  3. Add @CommandLine.Option and @CommandLine.Parametersannotations to receive argument and parameter values.

1. Define commands and subcommands

Each command can have one or more subcommands, and each subcommand can have further subcommands.

Add new commands as subcommands of CordaCommand. CordaCommand has three subcommands:

@CommandLine.Command(name = "corda",
        subcommands = [NodeCommand::class, FlowCommand::class, VaultCommand::class])
internal class CordaCommand : ParentCommand(), LoggingOwner

Business logic is typically implemented through subcommands. Create a new command as an empty child class of ParentCommand and define its subcommands as members of the @CommandLine.Command annotation.

See NodeCommand as an example:

@CommandLine.Command(name = "endpoint",
        subcommands = [AddNodeCommand::class,
            ListNodesCommand::class,
            RemoveNodeCommand::class,
            SetNodeCommand::class,
            GetNodeCommand::class],
        description = ["Performs operations on HTTP-RPC endpoints. HTTP-RPC endpoints should be created first before any subsequent commands " +
                "executed on them."])
internal class NodeCommand : ParentCommand()

2. Implement business logic and validation

Each subcommand has its own set of arguments and implements its own business logic. For each subcommand, you need to implement the business logic in the execute method.

ValidatedCommand

ValidatedCommand is the base class that implements validation to verify arguments passed into the command.

ValidatedCommand defines:

  • The execute method that you must override to provide the business logic:

    protected abstract fun execute(): Int
    
  • An empty validate method that you can override if validation is required:

    protected open fun validate() {}
    
  • the output method which you can use to print out results.

    See ListNodesCommandas a simple example:

    @CommandLine.Command(name = "list", description = [
        "Lists previously created HTTP-RPC endpoints along with their aliases."])
    internal class ListNodesCommand(private val storageService: StorageService) : ValidatedCommand() {
        override fun execute(): Int {
            storageService.getContexts().forEach {
                output("${it.name}: ${it.baseAddress}")
            }
            return ExitCodes.SUCCESS
        }
    }
    

EndpointOrAliasCommand

EndpointOrAliasCommand is a child of ValidatedCommand and defines an endpoint argument:

internal abstract class EndpointOrAliasCommand : ValidatedCommand() {
    @CommandLine.Option(names = ["--endpoint"], description = ["Url or alias for an existing endpoint."], required = false)
    var endpoint: String? = null
}

HttpRpcCommand

HttpRpcCommand extends EndpointOrAliasCommand. It adds the capability to get a proxy for an RPCOps interface. A command would typically extend HttpRpcCommand if its business logic needs to expose services via HTTP-RPC.

3. Annotate fields to receive command argument and parameter values

Picocli will initialize properly annotated fields with the matching arguments/positional parameters provided via the command line.

  • Fields annotated with @CommandLine.Option will be initialized with matching arguments.
  • Fields annotated with @CommandLine.Parameters will be initialized with positional parameters.

See AddNodeCommand as an example:

    @CommandLine.Option(names = ["-n", "--name"], description = ["Human readable name which will be used to identify HTTP-RPC endpoint"])
    var name: String? = null

    @CommandLine.Parameters(index = "0", description = ["HTTP-RPC endpoint URL in the form: https://<host>:port/api/v1"])
    lateinit var url: URL

Was this page helpful?

Thanks for your feedback!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.

We're sorry this page wasn't helpful. Let us know how we can make it better!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Create an issue

Create a new GitHub issue in this repository - submit technical feedback, draw attention to a potential documentation bug, or share ideas for improvement and general feedback.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.