{
  "markdown": "# RESTHeart CLI\n\nA command-line interface for RESTHeart plugin developers to automate the local install, build, run, and restart workflow.\n\n## Why this CLI exists\n\nDeveloping RESTHeart plugins often means repeating the same manual loop:\n\n-   install or update RESTHeart locally\n-   build plugin JARs with Maven or Gradle\n-   copy and deploy artifacts\n-   restart the server and verify status\n\nRESTHeart 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.\n\n## Overview\n\nRESTHeart CLI (`rh`) streamlines development and management of RESTHeart Java applications. It provides a single interface for common tasks such as:\n\n-   **Installing** and **updating** RESTHeart\n-   **Building** and **deploying** Java plugins\n-   **Starting** and **stopping** RESTHeart instances\n-   **Watching** for code changes and automatically rebuilding/redeploying\n\n### Developer Value\n\n-   **Faster development loop**: rebuild and restart automatically while coding\n-   **Fewer manual steps**: one CLI for build, deploy, run, status, and kill\n-   **Safer local operations**: explicit process and port management commands\n-   **Better version flexibility**: install from GitHub releases or local SNAPSHOT builds\n\n> 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.\n\nYou can use Maven or Gradle projects. By default, `rh` auto-detects the build system from project files.\n\n## Installation\n\n### Prerequisites\n\n-   Node.js (v18 or later)\n-   Java JDK (v21 or later)\n-   Maven (3.8 or later) or Gradle (7 or later), if not using the corresponding wrapper\n\n### Install from npm (recommended)\n\n```bash\nnpm install -g @softinstigate/rh\n# or use npx without global install:\nnpx @softinstigate/rh --help\n```\n\n### Install from source\n\n```bash\ngit clone https://github.com/SoftInstigate/restheart-cli.git\ncd restheart-cli\nnpm install\nnpm link\n```\n\n## Quick Start\n\n```bash\n# Install RESTHeart (latest version)\nrh install\n\n# Build and deploy your plugin\nrh build\n\n# Run RESTHeart\nrh run\n\n# Enable file watching (auto-rebuild on changes)\nrh watch\n```\n\nExpected outcomes:\n\n1. `rh install` downloads and installs RESTHeart into `.cache/restheart` in your project directory.\n2. `rh build` runs the auto-detected build system (Maven or Gradle) and deploys generated plugin JARs into RESTHeart's plugins directory.\n3. `rh run` starts RESTHeart (default HTTP port: 8080).\n4. `rh watch` monitors source/config changes and automatically rebuilds/restarts RESTHeart.\n\n👉 Look at the [Usage Guide](https://github.com/SoftInstigate/restheart-cli/blob/master/usage-guide.md) for more practical examples for common workflows.\n\n## Documentation\n\nThe project now includes a structured documentation set in `openwiki/`.\n\n-   [OpenWiki Quickstart](openwiki/quickstart.md)\n-   [OpenWiki Index](openwiki/index.md)\n-   [Architecture](openwiki/architecture/index.md)\n-   [Domain Concepts](openwiki/domain/index.md)\n-   [Operations Runbook](openwiki/operations/index.md)\n-   [Testing Guidance](openwiki/testing/index.md)\n-   [Development Workflows](openwiki/workflows/index.md)\n\n## Commands\n\n### Install RESTHeart\n\nInstall or update RESTHeart to a specific version, or from a local build:\n\n```bash\nrh install [version|path] [--force]\n```\n\nOptions:\n\n-   `version|path`: RESTHeart version (e.g., \"latest\", \"9.4.0\") or path to core/target directory (default: \"latest\")\n-   `--force`, `-f`: Force reinstallation even if already installed\n\nExamples:\n\n```bash\n# Install the latest version from GitHub releases\nrh install\n\n# Install a specific version from GitHub releases\nrh install 9.5.2\n\n# Install from local RESTHeart build (after mvn package)\nrh install ~/restheart/core/target\n\n# Install from local build (relative path)\nrh install ../restheart/core/target\n\n# Force reinstall from local build\nrh install ~/restheart/core/target --force\n```\n\n**Working with RESTHeart SNAPSHOT builds:**\n\nTo work with a locally built SNAPSHOT version of RESTHeart:\n\n```bash\n# 1. Build RESTHeart core\ncd ~/restheart\nmvn clean package  # builds to core/target/\n\n# 2. Install from local build in your plugin project\ncd ~/my-restheart-plugin\nrh install ~/restheart/core/target\n\n# 3. Start development (choose one mode)\n\n# Option A: run once\nrh run\n\n# Option B: watch mode (auto-rebuild/restart on changes)\nrh watch\n```\n\n### Build and Deploy\n\nBuild and deploy RESTHeart plugins from the current directory:\n\n```bash\nrh build\n```\n\nThis command:\n\n1. Builds the project using the selected build system (auto-detected Maven or Gradle)\n2. Deploys the built JARs to the RESTHeart plugins directory\n\n### Run RESTHeart\n\nStart or restart RESTHeart with optional configuration:\n\n```bash\nrh run [restheart-options..] [--build] [--port PORT]\n```\n\nOptions:\n\n-   `restheart-options`: Options to pass directly to RESTHeart (after -- separator)\n-   `--build`, `-b`: Build and deploy the plugin before running RESTHeart\n-   `--port`, `-p`: HTTP port for RESTHeart to listen on\n\nExamples:\n\n```bash\n# Run with default settings\nrh run\n\n# Run with custom configuration file\nrh run -- -o etc/localhost.yml\n\n# Build before running\nrh run --build\n```\n\n### Kill RESTHeart\n\nStop any running RESTHeart instances:\n\n```bash\nrh kill [--port PORT]\n```\n\nOptions:\n\n-   `--port`, `-p`: HTTP port of the RESTHeart instance to kill\n\n### Watch for Changes\n\nWatch for source changes, automatically rebuilding and restarting RESTHeart:\n\n```bash\nrh watch [--build] [--port PORT] [--debounce-time MS]\n```\n\nOptions:\n\n-   `--build`, `-b`: Build and deploy the plugin before starting the watch process\n-   `--port`, `-p`: HTTP port for RESTHeart to listen on\n-   `--debounce-time`: Time in milliseconds to wait after the last file change before rebuilding (default: 1000)\n\nExample:\n\n```bash\n# Watch source files with custom configuration\nrh watch -- -o etc/localhost.yml\n```\n\n### Check Status\n\nCheck if RESTHeart is currently running:\n\n```bash\nrh status [--port PORT]\n```\n\nOptions:\n\n-   `--port`, `-p`: HTTP port of the RESTHeart instance to check\n\n## Global Options\n\nThese options can be used with any command:\n\n-   `--version`: Display the version number of RESTHeart CLI\n-   `--debug`, `-d`: Run in debug mode with additional diagnostic information\n-   `--verbose`, `-v`: Show verbose output including debug messages\n-   `--quiet`, `-q`: Show only error messages and suppress other output\n-   `--timestamps`, `-t`: Add timestamps to log messages for better traceability\n-   `--build-system`: Build system preference (`auto`, `maven`, `gradle`) used by build/deploy workflows\n-   `--help`, `-h`: Show help information\n\n## Configuration\n\nRESTHeart CLI uses a configuration system that manages:\n\n-   Repository directory (current working directory)\n-   Cache directory (`.cache` in the repository directory)\n-   RESTHeart directory (`.cache/restheart` in the repository directory)\n-   HTTP port (default: 8080)\n-   Debug mode (default: false)\n-   Build system preference (default: `auto`)\n\nThese settings can be modified through command-line options or directly in the code.\n\n## Development Workflow\n\nA typical development workflow with RESTHeart CLI:\n\n1. Install RESTHeart: `rh install`\n2. Start with file watching: `rh watch`\n3. Make changes to your code\n4. RESTHeart CLI automatically detects changes, rebuilds and restarts\n5. Check status: `rh status`\n6. When done, stop RESTHeart: `rh kill`\n\n👉 Look at the [Usage Guide](https://github.com/SoftInstigate/restheart-cli/blob/master/usage-guide.md) for more practical examples for common workflows.\n\n## Troubleshooting\n\n### Common Issues\n\n#### RESTHeart fails to start\n\nCheck the log file in the repository directory (`restheart.log`) for error details.\n\n#### Build fails\n\nEnsure your selected build tool (Maven or Gradle) is correctly installed and the project structure is valid.\n\n#### Port already in use\n\nUse `rh kill` to stop any running instances, or specify a different port with `--port`.\n\n### Debug Mode\n\nFor more detailed information, enable debug mode:\n\n```bash\nrh --debug [command]\n```\n\n## Publishing to npm\n\nFor maintainers who need to publish a new version to npmjs.com:\n\n### Publishing Prerequisites\n\n-   You must be logged in to npm: `npm login`\n-   You must have publish permissions for the `@softinstigate/rh` package\n\n### Release Process\n\n1. **Update the version** in `package.json`:\n\n    ```bash\n    npm version patch  # for bug fixes\n    npm version minor  # for new features\n    npm version major  # for breaking changes\n    ```\n\n2. **Run quality checks**:\n\n    ```bash\n    npm run lint:check\n    npm run format:check\n    ```\n\n3. **Publish to npm**:\n\n    ```bash\n    npm publish --access public\n    ```\n\n4. **Push the version tag to GitHub**:\n\n    ```bash\n    git push && git push --tags\n    ```\n\n### Verify Publication\n\nAfter publishing, verify the package is available:\n\n```bash\nnpm view @softinstigate/rh\n```\n\n## License\n\nMIT\n\n## Contributors\n\n-   SoftInstigate <info@softinstigate.com>\n",
  "bytes": 9132,
  "sha": "44f3fc27488f8bbc568e1726c99e08912e950b4e9fb595107e6ed56b6c5ee40d",
  "repo_slug": "softinstigate/restheart-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_softinstigate_restheart_cli_openwiki_ind_5ebb5c5f/readme"
}