RESTHeart CLI

A command-line interface for RESTHeart plugin developers to automate the local install, build, run, and restart workflow.

Why this CLI exists

Developing RESTHeart plugins often means repeating the same manual loop:

• install or update RESTHeart locally
• build plugin JARs with Maven or Gradle
• copy and deploy artifacts
• restart the server and verify status

RESTHeart CLI (rh) removes this friction by turning that loop into a small set of predictable commands. It is focused on faster feedback during local development and less operational overhead while iterating.

Overview

RESTHeart CLI (rh) streamlines development and management of RESTHeart Java applications. It provides a single interface for common tasks such as:

• Installing and updating RESTHeart
• Building and deploying Java plugins
• Starting and stopping RESTHeart instances
• Watching for code changes and automatically rebuilding/redeploying

Developer Value

• Faster development loop: rebuild and restart automatically while coding
• Fewer manual steps: one CLI for build, deploy, run, status, and kill
• Safer local operations: explicit process and port management commands
• Better version flexibility: install from GitHub releases or local SNAPSHOT builds

You will typically begin with a Maven or Gradle project. Refer to the official documentation for detailed instructions on implementing custom plugins.

You can use Maven or Gradle projects. By default, rh auto-detects the build system from project files.

Installation

Prerequisites

• Node.js (v18 or later)
• Java JDK (v21 or later)
• Maven (3.8 or later) or Gradle (7 or later), if not using the corresponding wrapper

Install from npm (recommended)

npm install -g @softinstigate/rh
# or use npx without global install:
npx @softinstigate/rh --help

Install from source

git clone https://github.com/SoftInstigate/restheart-cli.git
cd restheart-cli
npm install
npm link

Quick Start

# Install RESTHeart (latest version)
rh install

# Build and deploy your plugin
rh build

# Run RESTHeart
rh run

# Enable file watching (auto-rebuild on changes)
rh watch

Expected outcomes:

1. rh install downloads and installs RESTHeart into .cache/restheart in your project directory.
2. rh build runs the auto-detected build system (Maven or Gradle) and deploys generated plugin JARs into RESTHeart's plugins directory.
3. rh run starts RESTHeart (default HTTP port: 8080).
4. rh watch monitors source/config changes and automatically rebuilds/restarts RESTHeart.

👉 Look at the Usage Guide for more practical examples for common workflows.

Commands

Install RESTHeart

Install or update RESTHeart to a specific version, or from a local build:

rh install [version|path] [--force]

Options:

• version|path: RESTHeart version (e.g., "latest", "9.4.0") or path to core/target directory (default: "latest")
• --force, -f: Force reinstallation even if already installed

Examples:

# Install the latest version from GitHub releases
rh install

# Install a specific version from GitHub releases
rh install 9.4.0

# Install from local RESTHeart build (after mvn package)
rh install ~/restheart/core/target

# Install from local build (relative path)
rh install ../restheart/core/target

# Force reinstall from local build
rh install ~/restheart/core/target --force

Working with RESTHeart SNAPSHOT builds:

To work with a locally built SNAPSHOT version of RESTHeart:

# 1. Build RESTHeart core
cd ~/restheart
mvn clean package  # builds to core/target/

# 2. Install from local build in your plugin project
cd ~/my-restheart-plugin
rh install ~/restheart/core/target

# 3. Start development (choose one mode)

# Option A: run once
rh run

# Option B: watch mode (auto-rebuild/restart on changes)
rh watch

Build and Deploy

Build and deploy RESTHeart plugins from the current directory:

rh build

This command:

1. Builds the project using the selected build system (auto-detected Maven or Gradle)
2. Deploys the built JARs to the RESTHeart plugins directory

Run RESTHeart

Start or restart RESTHeart with optional configuration:

rh run [restheart-options..] [--build] [--port PORT]

Options:

• restheart-options: Options to pass directly to RESTHeart (after -- separator)
• --build, -b: Build and deploy the plugin before running RESTHeart
• --port, -p: HTTP port for RESTHeart to listen on

Examples:

# Run with default settings
rh run

# Run with custom configuration file
rh run -- -o etc/localhost.yml

# Build before running
rh run --build

Kill RESTHeart

Stop any running RESTHeart instances:

rh kill [--port PORT]

Options:

• --port, -p: HTTP port of the RESTHeart instance to kill

Watch for Changes

Watch for source changes, automatically rebuilding and restarting RESTHeart:

rh watch [--build] [--port PORT] [--debounce-time MS]

Options:

• --build, -b: Build and deploy the plugin before starting the watch process
• --port, -p: HTTP port for RESTHeart to listen on
• --debounce-time: Time in milliseconds to wait after the last file change before rebuilding (default: 1000)

Example:

# Watch source files with custom configuration
rh watch -- -o etc/localhost.yml

Check Status

Check if RESTHeart is currently running:

rh status [--port PORT]

Options:

• --port, -p: HTTP port of the RESTHeart instance to check

Global Options

These options can be used with any command:

• --version: Display the version number of RESTHeart CLI
• --debug, -d: Run in debug mode with additional diagnostic information
• --verbose, -v: Show verbose output including debug messages
• --quiet, -q: Show only error messages and suppress other output
• --timestamps, -t: Add timestamps to log messages for better traceability
• --build-system: Build system preference (auto, maven, gradle) used by build/deploy workflows
• --help, -h: Show help information

Configuration

RESTHeart CLI uses a configuration system that manages:

• Repository directory (current working directory)
• Cache directory (.cache in the repository directory)
• RESTHeart directory (.cache/restheart in the repository directory)
• HTTP port (default: 8080)
• Debug mode (default: false)
• Build system preference (default: auto)

These settings can be modified through command-line options or directly in the code.

Development Workflow

A typical development workflow with RESTHeart CLI:

1. Install RESTHeart: rh install
2. Start with file watching: rh watch
3. Make changes to your code
4. RESTHeart CLI automatically detects changes, rebuilds and restarts
5. Check status: rh status
6. When done, stop RESTHeart: rh kill

👉 Look at the Usage Guide for more practical examples for common workflows.

Troubleshooting

Common Issues

RESTHeart fails to start

Check the log file in the repository directory (restheart.log) for error details.

Build fails

Ensure your selected build tool (Maven or Gradle) is correctly installed and the project structure is valid.

Port already in use

Use rh kill to stop any running instances, or specify a different port with --port.

Debug Mode

For more detailed information, enable debug mode:

rh --debug [command]

Publishing to npm

For maintainers who need to publish a new version to npmjs.com:

Publishing Prerequisites

• You must be logged in to npm: npm login
• You must have publish permissions for the @softinstigate/rh package

Release Process

1. Update the version in package.json:

   npm version patch  # for bug fixes
   npm version minor  # for new features
   npm version major  # for breaking changes

2. Run quality checks:

   npm run lint:check
   npm run format:check

3. Publish to npm:

   npm publish --access public

4. Push the version tag to GitHub:

   git push && git push --tags

Verify Publication

After publishing, verify the package is available:

npm view @softinstigate/rh

License

MIT

Contributors

• SoftInstigate info@softinstigate.com