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 <NODE_NAME> <COMMAND>

Examples with Real Values

Terminal

# Basic usage with a node named "node1"
meroctl --node node1 app list

# Using a different node name
meroctl --node my-production-node context list

# With additional options
meroctl --home ~/.calimero --node node1 app install my-app

Parameter Reference

Parameter	Description	Real Examples
<NODE_NAME>	Name of the node to connect to	node1, prod-node, test-node
<COMMAND>	Subcommand to execute	list, install, get, create
<EXECUTOR>	Identity/alias executing the call	3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf
<CONTEXT_ID>	Unique context identifier	3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf
<METHOD>	Method name to call	get_value, set_value, create_user
<app_id>	Application identifier	3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf
<blob_id>	Blob storage identifier	3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf
<context_id>	Context identifier	3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf
<alias>	User-friendly alias name	alice, bob, admin, user123
<path>	File system path	/path/to/node, ./my-node, ~/.calimero
<url>	Remote node URL	http://node.com, https://api.example.com

Commands:

• app Command for managing applications
• blob Command for managing blobs
• context Command for managing contexts
• call Call a method on a context
• peers Return the number of connected peers
• node Command for managing nodes
• 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:

Syntax	Description
meroctl --node <NODE_NAME> app <COMMAND>	Command for managing applications
meroctl --node <NODE_NAME> blob <COMMAND>	Command for managing blobs
meroctl --node <NODE_NAME> context <COMMAND>	Command for managing contexts
meroctl --node <NODE_NAME> call [OPTIONS] --as <EXECUTOR> <CONTEXT_ID> <METHOD>	Call a method on a context
meroctl --node <NODE_NAME> peers	Return the number of connected peers
meroctl --node <NODE_NAME> node <COMMAND>	Command for managing nodes

Practical Examples with Real Values

Command	Description
meroctl --node node1 app list	List all applications on node1
meroctl --node node1 blob list	List all blobs on node1
meroctl --node node1 context list	List all contexts on node1
meroctl --node node1 call --as 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf get_value	Call get_value method as executor
meroctl --node node1 peers	Show connected peers on node1
meroctl --node node1 node list	List configured nodes

Manage Applications

Syntax:

Terminal

meroctl --node <NODE_NAME> app <COMMAND>

Commands:

• get <app_id> - Fetch application details
• install <app_id> - Install an application
• list - List installed applications
• uninstall <app_id> - Uninstall an application

Real Examples:

# List all applications
meroctl --node node1 app list

# Install an application
meroctl --node node1 app install 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf

# Get details of a specific application
meroctl --node node1 app get 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf

# Uninstall an application
meroctl --node node1 app uninstall 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf

Commands:

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

Manage Blobs

Syntax:

Terminal

meroctl --node <NODE_NAME> blob <COMMAND>

Commands:

• list - List all blobs
• info <blob_id> - Get information about a specific blob
• delete <blob_id> - Delete a specific blob

Real Examples:

# List all blobs
meroctl --node node1 blob list

# Get information about a specific blob
meroctl --node node1 blob info 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf

# Delete a specific blob
meroctl --node node1 blob delete 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf

Commands:

• list List all blobs
• info Get information about a specific blob
• delete Delete a specific blob

Manage Contexts

Syntax:

Terminal

meroctl --node <NODE_NAME> context <COMMAND>

Commands:

• list - List all contexts
• create --application-id <app_id> - Create a new context
• join <context_id> - Join an existing context
• get <context_id> - Get context details
• watch <context_id> - Watch context events
• delete <context_id> - Delete a context
• update <context_id> - Update app in context
• identity <COMMAND> - Manage context identities
• alias <COMMAND> - Manage context aliases
• use <context_id> - Set the default context
• proposals <COMMAND> - Manage proposals within a context
• sync <context_id> - Explicitly request a sync

Real Examples:

# List all contexts
meroctl --node node1 context list

# Create a new context
meroctl --node node1 context create --application-id 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf

# Join an existing context
meroctl --node node1 context join 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf

# Get context details
meroctl --node node1 context get 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf

# Watch context events
meroctl --node node1 context watch 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf

# Delete a context
meroctl --node node1 context delete 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf

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

• delete Delete a context

• watch Watch events from a context and optionally execute commands

• update Update app in context

• identity Manage context identities

• use Set the default context

• proposals Manage proposals within a context

• sync Explicitly request a sync

  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> context identity <COMMAND>

Commands:

• list List identities in a context

  • Use --owned to get only owned identities

    meroctl --node <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> context <COMMAND>

The alias subcommand structure:

meroctl --node <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 Nodes

Syntax:

Terminal

meroctl --node <NODE_NAME> node <COMMAND>

Commands:

• list - List all configured nodes
• add <alias> <path_or_url> - Add or connect to a node
• remove <alias> - Remove a node connection
• use <alias> - Set a node as active (default for commands)

Real Examples:

# List all configured nodes
meroctl --node node1 node list

# Add a new local node
meroctl --node node1 node add node2 /path/to/node2

# Add a remote node
meroctl --node node1 node add remote-node http://remote-node.com

# Set a node as active
meroctl --node node1 node use node2

# Remove a node connection
meroctl --node node1 node remove node2

Commands:

• add Add or connect to a node
• remove Remove a node connection
• use Set a node as active (default for commands)
• list List all configured nodes

Manage Identities

Syntax:

Terminal

meroctl --node <NODE_NAME> identity <COMMAND>

Commands:

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

Real Examples:

# Generate a new key pair
meroctl --node node1 identity generate

# List identities in a context
meroctl --node node1 context identity list 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf

# List only owned identities
meroctl --node node1 context identity list 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf --owned

Commands:

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

Show connected peers

Syntax:

Terminal

meroctl --node <NODE_NAME> peers

Real Examples:

# Show peers for default node
meroctl --node node1 peers

# Show peers with JSON output
meroctl --node node1 peers --output-format json

Call a method on a context

Syntax:

Terminal

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

Arguments:

• <CONTEXT_ID> - ContextId of the context
• <METHOD> - Method to call on the context

Options:

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

Real Examples:

# Call a simple method
meroctl --node node1 call --as 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf get_value

# Call with arguments
meroctl --node node1 call --as 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf set_value --args '{"key": "name", "value": "John"}'

# Call with specific ID
meroctl --node node1 call --as 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf 3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf create_user --id user-123

Arguments:

• <CONTEXT_ID> ContextId of the context
• <METHOD> Method to call on the context

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]