Metal-CLI Commands

Metal-CLI is a command-line tool that gives developers access to everything Metal Blockchain. This release specializes in helping developers build and test Subnets.

To get started, look at the documentation for the subcommands or jump right in with metal subnet create myNewSubnet.

Subnet

The subnet command suite provides a collection of tools for developing and deploying Subnets.

To get started, use the subnet create command wizard to walk through the configuration of your very first Subnet. Then, go ahead and deploy it with the subnet deploy command. You can use the rest of the commands to manage your Subnet configurations and live deployments.

Subnet AddValidator

The subnet addValidator command whitelists a primary network validator to validate the provided deployed Subnet.

To add the validator to the Subnet's allow list, you first need to provide the subnetName and the validator's unique NodeID. The command then prompts for the validation start time, duration, and stake weight. You can bypass these prompts by providing the values with flags.

This command currently only works on Subnets deployed to either the Tahoe Testnet or Mainnet.

Usage:

metal subnet addValidator [subnetName] [flags]

Flags:

    --tahoe tahoe                  join on Tahoe (alias for `testnet`)
-h, --help                       help for addValidator
-k, --key string                 select the key to use [tahoe deploy only]
-g, --ledger                     use ledger instead of key (always true on mainnet, defaults to false on tahoe)
    --ledger-addrs strings       use the given ledger addresses
    --mainnet mainnet            join on mainnet
    --nodeID string              set the NodeID of the validator to add
    --output-tx-path string      file path of the add validator tx
    --staking-period duration    how long this validator will be staking
    --start-time string          UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
    --subnet-auth-keys strings   control keys that will be used to authenticate add validator tx
    --testnet testnet            join on testnet (alias for `tahoe`)
    --weight uint                set the staking weight of the validator to add

Subnet Configure

MetalGo nodes support several different configuration files. Subnets have their own Subnet config which applies to all chains/VMs in the Subnet. Each chain within the Subnet can have its own chain config. This command allows you to set both config files.

Usage:

metal subnet configure [subnetName] [flags]

Flags:

    --chain-config string            path to the chain configuration
-h, --help                           help for configure
    --per-node-chain-config string   path to per node chain configuration for local network
    --subnet-config string           path to the subnet configuration

Subnet Create

The subnet create command builds a new genesis file to configure your Subnet. By default, the command runs an interactive wizard. It walks you through all the steps you need to create your first Subnet.

The tool supports deploying Subnet-EVM, SpacesVM, and custom VMs. You can create a custom, user-generated genesis with a custom VM by providing the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a subnetName that already exists causes the command to fail. If you’d like to overwrite an existing configuration, pass the -f flag.

Usage:

metal subnet create [subnetName] [flags]

Flags:

    --custom              use a custom VM template
    --evm                 use the SubnetEVM as the base template
-f, --force               overwrite the existing configuration if one exists
    --genesis string      file path of genesis to use
-h, --help                help for create
    --latest              use latest VM version, takes precedence over --vm-version
    --spacesvm            use the SpacesVM as the base template
    --vm string           file path of custom vm to use
    --vm-version string   version of vm template to use

Subnet Delete

The subnet delete command deletes an existing Subnet configuration.

Usage:

metal subnet delete [flags]

Flags:

-h, --help help for delete

Subnet Deploy

The subnet deploy command deploys your Subnet configuration locally, to Tahoe Testnet, or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the Subnet.

Metal-CLI only supports deploying an individual Subnet once per network. Subsequent attempts to deploy the same Subnet to the same network (local, Tahoe, Mainnet) aren't allowed. If you'd like to redeploy a Subnet locally for testing, you must first call metal network clean to reset all deployed chain state. Subsequent local deploys redeploy the chain with fresh state. You can deploy the same Subnet to multiple networks, so you can take your locally tested Subnet and deploy it on Tahoe or Mainnet.

Usage:

metal subnet deploy [subnetName] [flags]

Flags:

    --metalgo-version string   use this version of metalgo (ex: v1.17.12) (default "latest")
    --control-keys strings         addresses that may make subnet changes
-f, --tahoe testnet                 deploy to tahoe (alias to testnet
-h, --help                         help for deploy
-k, --key string                   select the key to use [tahoe deploy only]
-g, --ledger                       use ledger instead of key (always true on mainnet, defaults to false on tahoe)
    --ledger-addrs strings         use the given ledger addresses
-l, --local                        deploy to a local network
-m, --mainnet                      deploy to mainnet
    --output-tx-path string        file path of the blockchain creation tx
-s, --same-control-key             use creation key as control key
    --subnet-auth-keys strings     control keys that will be used to authenticate chain creation
-t, --testnet tahoe                 deploy to testnet (alias to tahoe)
    --threshold uint32             required number of control key signatures to make subnet changes

Subnet Describe

The subnet describe command prints the details of a Subnet configuration to the console. By default, the command prints a summary of the configuration. By providing the --genesis flag, the command instead prints out the raw genesis file.

Usage:

metal subnet describe [subnetName] [flags]

Flags:

-g, --genesis   Print the genesis to the console directly instead of the summary
-h, --help      help for describe

Subnet Export

The subnet export command write the details of an existing Subnet deploy to a file.

The command prompts for an output path. You can also provide one with the --output flag.

Usage:

metal subnet export [subnetName] [flags]

Flags:

-h, --help            help for export
-o, --output string   write the export data to the provided file path

Subnet Import

The subnet import command imports configurations into Metal-CLI.

This command supports importing from a file created on another computer, or importing from Subnets running public networks (for example, created manually or with the deprecated Subnet-CLI)

Import from a File

To import from a file, you can optionally provide the path as a command-line argument. Alternatively, running the command without any arguments triggers an interactive wizard. To import from a repository, go through the wizard. By default, an imported Subnet doesn't overwrite an existing Subnet with the same name. To allow overwrites, provide the --force flag.

Usage:

metal subnet import file [subnetPath] [flags]

Flags:

    --branch string   the repo branch to use if downloading a new repo
-f, --force           overwrite the existing configuration if one exists
-h, --help            help for import
    --repo string     the repo to import (ex: MetalBlockchain/metal-plugins-core) or url to download the repo from
    --subnet string   the subnet configuration to import from the provided repo

Import from a Public Network

The subnet import public command will import a Subnet configuration from a running network.

The genesis file should be available from the disk for this to work. By default, an imported Subnet will not overwrite an existing Subnet with the same name. To allow overwrites, provide the --force flag.

Usage:

metal subnet import public [subnetPath] [flags]

Flags:

    --custom                     use a custom VM template
    --evm                        import a subnet-evm
-f, --force                      overwrite the existing configuration if one exists
    --tahoe tahoe                  import from tahoe (alias for `testnet`)
    --genesis-file-path string   path to the genesis file
-h, --help                       help for public
    --mainnet mainnet            import from mainnet
    --node-url string            [optional] URL of an already running subnet validator
    --spacesvm                   use the SpacesVM as the base template
    --subnet-id string           the subnet ID
    --testnet testnet            import from testnet (alias for `tahoe`)

Subnet Join

The subnet join command configures your validator node to begin validating a new Subnet.

To complete this process, you must have access to the machine running your validator. If the CLI is running on the same machine as your validator, it can generate or update your node's config file automatically. Alternatively, the command can print the necessary instructions to update your node manually. To complete the validation process, the Subnet's admins must add the NodeID of your validator to the Subnet's allow list by calling addValidator with your NodeID.

After you update your validator's config, you need to restart your validator manually. If you provide the --metalgo-config flag, this command attempts to edit the config file at that path.

This command currently only supports Subnets deployed on the Tahoe Testnet and Mainnet.

Usage:

metal subnet join [subnetName] [flags]

Flags:

    --metalgo-config string   file path of the metalgo config file
    --fail-if-not-validating      fail if whitelist check fails
    --force-whitelist-check       if true, force the whitelist check
    --force-write                 if true, skip to prompt to overwrite the config file
    --tahoe tahoe                   join on tahoe (alias for `testnet`)
-h, --help                        help for join
    --mainnet mainnet             join on mainnet
    --nodeID string               set the NodeID of the validator to check
    --plugin-dir string           file path of metalgo's plugin directory
    --print                       if true, print the manual config without prompting
    --skip-whitelist-check        if true, skip the whitelist check
    --testnet testnet             join on testnet (alias for `tahoe`)

Subnet List

The subnet list command prints the names of all created Subnet configurations. Without any flags, it will print some general, static information about the Subnet. With the --deployed flag, information such as VMID, BlockchainID and SubnetID will be shown.

Usage:

metal subnet list [flags]

Flags:

    --deployed   show additional deploy information
-h, --help       help for list

Subnet Publish

The subnet publish command publishes the Subnet's VM to a repository.

Usage:

metal subnet publish [subnetName] [flags]

Flags:

    --alias string              We publish to a remote repo, but identify the repo locally under a user-provided alias (e.g. myrepo).
    --force                     If true, ignores if the subnet has been published in the past, and attempts a forced publish.
-h, --help                      help for publish
    --no-repo-path string       Do not let the tool manage file publishing, but have it only generate the files and put them in the location given by this flag.
    --repo-url string           The URL of the repo where we are publishing
    --subnet-file-path string   Path to the Subnet description file. If not given, a prompting sequence will be initiated.
    --vm-file-path string       Path to the VM description file. If not given, a prompting sequence will be initiated.

Subnet Stats

The subnet stats command prints validator statistics for the given Subnet.

Usage:

metal subnet stats [subnetName] [flags]

Flags:

    --tahoe tahoe         print stats on tahoe (alias for `testnet`)
-h, --help              help for stats
    --mainnet mainnet   print stats on mainnet
    --testnet testnet   print stats on testnet (alias for `tahoe`)

Network

The network command suite provides a collection of tools for managing local Subnet deployments.

When you deploy a Subnet locally, it runs on a local, multi-node Metal network. The subnet deploy command starts this network in the background. This command suite allows you to shutdown, restart, and clear that network.

This network currently supports multiple, concurrently deployed Subnets.

Network Clean

The network clean command shuts down your local, multi-node network. All deployed Subnets shutdown and delete their state. You can restart the network by deploying a new Subnet configuration.

Usage:

metal network clean [flags]

Flags:

    --hard   Also clean downloaded metalgo and plugin binaries
-h, --help   help for clean

Network Start

The network start command starts a local, multi-node Metal network on your machine.

By default, the command loads the default snapshot. If you provide the --snapshot-name flag, the network loads that snapshot instead. The command fails if the local network is already running.

Usage:

metal network start [flags]

Flags:

    --metalgo-version string   use this version of metalgo (ex: v1.17.12) (default "latest")
-h, --help                         help for start
    --snapshot-name string         name of snapshot to use to start the network from (default "default-1654102509")

Network Status

The network status command prints whether or not a local Metal network is running and some basic stats about the network.

Usage:

metal network status [flags]

Flags:

-h, --help   help for status

Network Stop

The network stop command shuts down your local, multi-node network.

All deployed Subnets shutdown gracefully and save their state. If you provide the --snapshot-name flag, the network saves its state under this named snapshot. You can reload this snapshot with network start --snapshot-name <snapshotName>. Otherwise, the network saves to the default snapshot, overwriting any existing state. You can reload the default snapshot with network start.

Usage:

metal network stop [flags]

Flags:

-h, --help                   help for stop
    --snapshot-name string   name of snapshot to use to save network state into (default "default-1654102509")

Transaction

The transaction command suite provides all of the utilities required to sign multisig transactions.

Transaction Commit

The transaction commit command commits a transaction by submitting it to the P-Chain.

Usage:

metal transaction commit [subnetName] [flags]

Flags:

-h, --help                       help for commit
    --input-tx-filepath string   Path to the transaction signed by all signatories

Transaction Sign

The transaction sign command signs a multisig transaction.

Usage:

metal transaction sign [subnetName] [flags]

Flags:

-h, --help                       help for sign
    --input-tx-filepath string   Path to the transaction file for signing
-k, --key string                 select the key to use [tahoe only]
-g, --ledger                     use ledger instead of key (always true on mainnet, defaults to false on tahoe)
    --ledger-addrs strings       use the given ledger addresses

Key

The key command suite provides a collection of tools for creating and managing signing keys. You can use these keys to deploy Subnets to the Tahoe Testnet, but these keys are NOT suitable to use in production environments. DO NOT use these keys on Mainnet.

To get started, use the key create command.

Key Create

The key create command generates a new private key to use for creating and controlling test Subnets. Keys generated by this command are NOT cryptographically secure enough to use in production environments. DO NOT use these keys on Mainnet.

The command works by generating a secp256 key and storing it with the provided keyName. You can use this key in other commands by providing this keyName.

If you'd like to import an existing key instead of generating one from scratch, provide the --file flag.

Usage:

metal key create [keyName] [flags]

Flags:

    --file string   import the key from an existing key file
-f, --force         overwrite an existing key with the same name
-h, --help          help for create

Key Delete

The key delete command deletes an existing signing key.

To delete a key, provide the keyName. The command prompts for confirmation before deleting the key. To skip the confirmation, provide the --force flag.

Usage:

metal key delete [keyName] [flags]

Flags:

-f, --force   delete the key without confirmation
-h, --help    help for delete

Key Export

The key export command exports a created signing key. You can use an exported key in other applications or import it into another instance of Metal-CLI.

By default, the tool writes the hex encoded key to stdout. If you provide the --output flag, the command writes the key to a file of your choosing.

Usage:

metal key export [keyName] [flags]

Flags:

-h, --help            help for export
-o, --output string   write the key to the provided file path

Key List

The key list command prints information for all stored signing keys or for the ledger addresses associated to certain indices.

Usage:

metal key list [flags]

Flags:

-a, --all-networks   list all network addresses
-c, --cchain         list C-Chain addresses (default true)
-f, --tahoe           list testnet (tahoe) network addresses
-h, --help           help for list
-g, --ledger uints   list ledger addresses for the given indices (default [])
-l, --local          list local network addresses
-m, --mainnet        list mainnet network addresses
-t, --testnet        list testnet (tahoe) network addresses