HarperFast / HarperFast/harper

CLI: friendly error message when Harper isn't running (not raw ECONNREFUSED)

Open
#658 0 comments 0 reactions 0 assignees View on GitHub
area:cli enhancement from-jira
Dominant language
JavaScript
Stars
89
Forks
10
Avg merge
2d 6h
Merged PRs (30d)
200

Description

When you run a CLI command (e.g. `harperdb status`) while Harper is not running, the error is a raw `ECONNREFUSED` from the socket connection attempt. We should detect this and emit a friendlier message.

## Suggested behavior

```
$ harperdb status
Harper is not running. Use `harperdb run` (or `harperdb start`) to start it.
```

Instead of a Node.js stack trace ending in `Error: connect ECONNREFUSED ...`.

## Implementation notes

- The CLI already knows when it's connecting to the local instance vs. a remote one. For the local path, when the connect fails with `ECONNREFUSED` (or `ENOENT` on the Unix domain socket — see [HarperFast/harper#585](https://github.com/HarperFast/harper/issues/585)), substitute a friendly message.
- Exit code should remain non-zero (see [HarperFast/harper#584](https://github.com/HarperFast/harper/issues/584)).
- For remote targets, the existing error is more informative — keep it.

## Acceptance criteria

- `harperdb status` (and any other CLI command targeting the local instance) prints a clear message when Harper isn't running, no stack trace.
- Exit code is non-zero.
- Test covering the "Harper not running" case.

---

🤖 Filed by Claude on behalf of Kris.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.