Files
Bundle OKF 0.2 · 6 conceitos · SoftInstigate/restheart-cli
Open source Repository Open in the app JSON README (API)
About
# Files
- [RESTHeart CLI Quickstart](quickstart.md) - Getting started with RESTHeart CLI - installation, basic usage, and navigation to detailed documentation
# Directories
- [architecture](architecture/)
- [domain](domain/)
- [operations](operations/)
- [testing](testing/)
- [workflows](workflows/)
Details
- Kind
- OKF bundles
- Topic
- Developer tools
- Publisher
- softinstigate
- Origin
- okf_github
- Category
- dados
- Version
- 0.2
- Stars
- 3
- Last push
- 2026-08-29T17:47:50Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-09-08 02:17:33
- Updated
- 2026-09-08 02:17:33
- Origin id
SoftInstigate/restheart-cli:openwiki/index.md
README
# 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](https://restheart.org/docs/plugins/overview) 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)
```bash
npm install -g @softinstigate/rh
# or use npx without global install:
npx @softinstigate/rh --help
```
### Install from source
```bash
git clone https://github.com/SoftInstigate/restheart-cli.git
cd restheart-cli
npm install
npm link
```
## Quick Start
```bash
# 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](https://github.com/SoftInstigate/restheart-cli/blob/master/usage-guide.md) for more practical examples for common workflows.
## Documentation
The project now includes a structured documentation set in `openwiki/`.
- [OpenWiki Quickstart](openwiki/quickstart.md)
- [OpenWiki Index](openwiki/index.md)
- [Architecture](openwiki/architecture/index.md)
- [Domain Concepts](openwiki/domain/index.md)
- [Operations Runbook](openwiki/operations/index.md)
- [Testing Guidance](openwiki/testing/index.md)
- [Development Workflows](openwiki/workflows/index.md)
## Commands
### Install RESTHeart
Install or update RESTHeart to a specific version, or from a local build:
```bash
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:
```bash
# Install the latest version from GitHub releases
rh install
# Install a specific version from GitHub releases
rh install 9.5.2
# 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:
```bash
# 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:
```bash
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:
```bash
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:
```bash
# 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:
```bash
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:
```bash
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:
```bash
# Watch source files with custom configuration
rh watch -- -o etc/localhost.yml
```
### Check Status
Check if RESTHeart is currently running:
```bash
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](https://github.com/SoftInstigate/restheart-cli/blob/master/usage-guide.md) 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:
```bash
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`:
```bash
npm version patch # for bug fixes
npm version minor # for new features
npm version major # for breaking changes
```
2. **Run quality checks**:
```bash
npm run lint:check
npm run format:check
```
3. **Publish to npm**:
```bash
npm publish --access public
```
4. **Push the version tag to GitHub**:
```bash
git push && git push --tags
```
### Verify Publication
After publishing, verify the package is available:
```bash
npm view @softinstigate/rh
```
## License
MIT
## Contributors
- SoftInstigate <info@softinstigate.com>