Meroctl

Meroctl is a command-line tool that enables you to interact with your Calimero node directly from the shell.

Installation

You can choose to install meroctl using either the installation script or Homebrew.

Homebrew

If you use Homebrew, you can install meroctl directly with the following steps:

Steps

1. Add the Calimero Homebrew tap:

   brew tap calimero-network/homebrew-tap

2. Install merod:

   brew install meroctl

3. Verify the installation:

   meroctl --version

If the version number appears, the installation was successful.

Installation Script

The installation script supports multiple terminal environments and will automatically configure your PATH based on your shell.

Steps

1. Open your terminal and run:

   curl -sSf https://raw.githubusercontent.com/calimero-network/install-sh/master/install-meroctl.sh | bash

2. Source the updated PATH:

   source <your-shell-config-file>

   Replace <your-shell-config-file> with .bashrc, .zshrc, or the relevant configuration file for your shell.

3. Verify the installation:

   meroctl --version

If the version number appears, the installation was successful.

Notes for Shell Environments

The script automatically updates your PATH based on your shell configuration:

• Bash: Updates .bashrc.
• Zsh: Updates .zshrc.
• Fish: Modifies ~/.config/fish/config.fish.
• Csh/Tcsh: Updates .cshrc.

To apply the changes immediately, use the source command as described in step 2 above.

Usage

Terminal

meroctl [OPTIONS] --node-name <NAME> <COMMAND>

Commands:

• app Command for managing applications
• context Command for managing contexts
• identity Command for creating an empty identity
• proxy Command for managing proxy contract
• call Executing read and write RPC calls
• peers Show a number of connected peers
• bootstrap Setup two nodes inside the same context
• help Print this message or the help of the given subcommand(s)

tip

Run help to get more information about the available options and commands.

Terminal

meroctl --help

Options:

• --home <PATH> Directory for config and data
• -n, --node-name <NAME> Name of node
• -h, --help Print help
• -output-format <FORMAT> [default: plain-text] [possible values: json, plain-text]
• -V, --version Print version

tip

Default location of the config and data directory is ~/.calimero. You can change the location by using the --home option.

note

All of the communication with your node through the meroctl CLI is protected by your nodes private key.

Examples:

Command	Description
meroctl --node-name <NAME> app <COMMAND>	Command for managing applications
meroctl --node-name <NAME> context <COMMAND>	Command for managing contexts
meroctl --node-name <NAME> identity <COMMAND>	Command for creating identities
meroctl --node-name <NAME> proxy <COMMAND>	Command for managing proxy contract
meroctl --node-name <NAME> call [OPTIONS] --as <EXECUTOR> <CONTEXT_ID> <METHOD>	Executing read and write RPC calls

Manage Applications

Terminal

meroctl --node-name <NAME> app <COMMAND>

Commands:

• get Fetch application details
• install Install an application
• list List installed applications

Manage Contexts

Terminal

meroctl --node-name <NAME> context <COMMAND>

Commands:

• alias Create an alias for a context

• list List all contexts

• create Create a new context

• join Join an application context

• invite Create invitation to a context for a invitee

• get Fetch details about the context

  Details

  get subcommands

  - info Get context information - client-keys Get client keys - storage Get storage information

• identity Create or list a context identity or it's alias

• delete Delete a context

• watch Watch events from a context

• update Update app in context

• peers Show a number of connected peers

Managing Context Identities and Aliases

The context identity command supports alias management to simplify working with public keys across contexts:

meroctl --node-name <NAME> context identity <COMMAND>

Commands:

• list List identities in a context

  • Use --owned to get only owned identities

    meroctl --node-name <NAME> context identity list <contextId or alias> --owned

• alias Manage identity aliases

  • add <name> <identity> --context <context-id or alias> Create new alias for an identity
  • remove <name> --context <context-id or alias> Remove an identity alias
  • get <name> --context <context-id or alias> Look up an identity's hash by alias

Context Management with Aliases

The context command includes alias management as a subcommand to simplify working with context IDs:

meroctl --node-name <NAME> context <COMMAND>

The alias subcommand structure:

meroctl --node-name <NAME> context alias <COMMAND>

• add <name> <context-id> Create new alias for a context
• remove <name> Remove a context alias
• get <name> Look up a context by alias

Additional context commands support using aliases:

• create --as <alias> ... Create context with an identity alias
• get <context-alias> Get context info using alias
• invite <context-alias> <invitee-alias> --as <inviter-alias> Create invitation using aliases
• And more...

tip

See the Invitations and Joinings guide for detailed examples of using aliases to streamline context management.

Manage Identities

Terminal

meroctl --node-name <NAME> identity <COMMAND>

Commands:

• generate Generate public/private key pair used for context identity

Command for managing proxy contract

Terminal

 meroctl --node-name <NAME> proxy <COMMAND>

Commands:

• get Fetch details about the proxy contract

Show a number of connected peers

Terminal

meroctl --node-name <NAME> peers

Executing read and write RPC calls

Terminal

meroctl --node-name <NAME> call [OPTIONS] --as <EXECUTOR> <CONTEXT_ID> <METHOD>

Arguments:

• <CONTEXT_ID> ContextId of the context
• <METHOD> Method to fetch details

Options:

• --args <ARGS> JSON arguments to pass to the method
• --as <EXECUTOR> Public key of the executor
• --id <ID> Id of the RPC execute call [default: dontcare]

Setup two nodes inside the same context

Terminal

meroctl --node-name <NAME> bootstrap <COMMAND> --merod-path <MEROD_PATH> --protocol <PROTOCOL> --app-path [APP_PATH]

Command initializes and run node1 and node2 in the same context.

Arguments:

• <MEROD_PATH> Full path to merod binary.
• <PROTOCOL> One of supported protocols for context creation. (e.g. near, starknet, icp, stellar)
• <APP_PATH> Path to the app wasm file. If not specified, the default core-template-app will be used

Commands:

• start: Start bootstrap process