@nearhost/cli 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +87 -6
  2. package/package.json +25 -9
package/README.md CHANGED
@@ -1,20 +1,101 @@
1
- # @nearhost/cli
1
+ [![Nearhost. Run it anywhere. Open it here.](https://raw.githubusercontent.com/nearhost/.github/main/assets/header-npm.png)](https://nearhost.dev)
2
2
 
3
- [Nearhost](https://nearhost.dev) gives every local and remote development server an address at `https://<name>.test`, with a certificate your browser trusts and SSH forwards that look after themselves.
3
+ # Nearhost
4
+
5
+ Nearhost is a terminal app that opens a dev server running on one of your other machines at a local `https://myapp.test`, over the SSH config you already have. You install nothing on the server, and cookies, OAuth redirects, WebSockets and hot reload behave as they do on `localhost`.
4
6
 
5
7
  ```sh
6
8
  npx @nearhost/cli
7
9
  ```
8
10
 
9
- or install it for good:
11
+ [Website](https://nearhost.dev) · [Docs](https://nearhost.dev/docs/getting-started/introduction/) · [GitHub](https://github.com/nearhost/nearhost) · [Releases](https://github.com/nearhost/nearhost/releases)
12
+
13
+ ![The Nearhost terminal interface: servers and projects on the left, and the selected project's address, routes and request log on the right.](https://raw.githubusercontent.com/nearhost/.github/main/assets/tui.png)
14
+
15
+ ## Why Nearhost
16
+
17
+ You write code on a laptop and run it somewhere else: a desktop under the desk, a home server, a VPS, or a container on this machine. The app listens on `localhost` over there, and your browser sits over here. Today that means an `ssh -L` flag for every port, plain HTTP that breaks secure cookies and OAuth callbacks, and hot reload that fails when you miss a port.
18
+
19
+ Nearhost gives each project a name, a certificate your browser trusts and SSH forwards that reconnect on their own. Add a project once and you reach it at `https://myapp.test` today, tomorrow and after a reboot.
20
+
21
+ - **One address per project.** Each project keeps a stable `.test` name, so bookmarks, cookies and OAuth callbacks keep working.
22
+ - **Real HTTPS, trusted once.** Nearhost creates its own local certificate authority on first run, and you trust it once. Secure cookies and service workers behave as they do in production. No shared key ships in the binary, so nobody else can mint certificates for your names.
23
+ - **Your own SSH.** Nearhost runs OpenSSH, so `Include`, `Match`, ProxyJump, agent forwarding and keychain identities apply. If `ssh mini` works without a prompt, Nearhost works.
24
+ - **Nothing on the server.** No agent, no config change and no open port. Your dev server keeps listening on `localhost`.
25
+ - **Hot reload and WebSockets.** Upgrades travel through the same SSH connection as the page. Nearhost can forward a dev server's port to the same number on your laptop, so asset URLs that point at `localhost` still resolve.
26
+ - **Any stack.** If it listens on a port, Nearhost can serve it. It reads port variables from `.env` and proposes routes. Presets from a registry you trust add Docker Compose, Vite and Laravel Sail.
27
+ - **Local projects too.** Projects on your laptop get the same name and certificate, so one tool covers the laptop and the servers.
28
+ - **Your traffic stays yours.** No relay, no account and no public URL. Nearhost owns one marked block in `/etc/hosts` and asks for `sudo` only when that block changes.
29
+
30
+ ## Install
31
+
32
+ Run it once with npx:
33
+
34
+ ```sh
35
+ npx @nearhost/cli
36
+ ```
37
+
38
+ Or install the `nearhost` command for good:
10
39
 
11
40
  ```sh
12
41
  npm install -g @nearhost/cli
13
42
  nearhost
14
43
  ```
15
44
 
16
- This package holds a small launcher. The binary comes in a platform package, `@nearhost/cli-<os>-<arch>`, which npm picks for your machine: macOS or Linux, on x64 or arm64. Nothing is downloaded by an install script, so it works with `--ignore-scripts`, pnpm and bun.
45
+ pnpm (`pnpm add -g @nearhost/cli`) and bun (`bun add -g @nearhost/cli`) work too. Nearhost runs on macOS and Linux, on Apple silicon, Intel and ARM.
46
+
47
+ The binary also ships through Homebrew (`brew install nearhost/tap/nearhost`) and a shell installer (`curl -fsSL https://nearhost.dev/install.sh | sh`). The [install guide](https://nearhost.dev/docs/getting-started/install/) covers each one.
48
+
49
+ ### On Linux
50
+
51
+ Nearhost serves HTTPS on port 443 and redirects port 80, and a normal user cannot bind either. Run `nearhost doctor`: it prints the `setcap` command that grants the binary that one capability, with the binary's path inside `node_modules` filled in. Run it again after each upgrade.
52
+
53
+ ## Quick start
54
+
55
+ 1. **Start Nearhost.** Run `nearhost`. On first run it explains its local certificate authority and trusts it for you, asking for your password through `sudo`.
56
+ 2. **Add a server.** Press `s` and pick a host alias from `~/.ssh/config`, or type `user@host`. Nearhost checks that it connects without a prompt. The `local` server needs no setup.
57
+ 3. **Add a project.** Press `n` and give the project's path. Nearhost reads its `.env` over SFTP and proposes the ports: which one serves the web app, which need a loopback forward and which to ignore.
58
+ 4. **Open it.** Nearhost adds a hosts entry, issues a certificate and routes `https://myapp.test` through the SSH connection. Press `o` to open it in your browser.
59
+
60
+ Press `?` in the app for every key. For scripts and terminals without a screen, `nearhost up` serves the same projects headless until you press Ctrl-C.
61
+
62
+ ## From a coding agent
63
+
64
+ Coding agents can add the project they work in, on this machine or on a server Nearhost connects to. Install the skill for Claude Code, Codex, Cursor, Gemini CLI and other agents that read skills:
65
+
66
+ ```sh
67
+ npx skills add nearhost/nearhost -g
68
+ ```
69
+
70
+ Then ask the agent to add the project, with `/nearhost add` in Claude Code. Nearhost opens the add form already filled in, and nothing changes until you save it. [Read more](https://nearhost.dev/docs/getting-started/use-a-coding-agent/).
71
+
72
+ ## Commands
73
+
74
+ | Command | What it does |
75
+ | --- | --- |
76
+ | `nearhost` | Open the full-screen view and serve every enabled project |
77
+ | `nearhost add [path]` | Add a project, discovering its ports from its files |
78
+ | `nearhost ls` | List the configured projects and their routes |
79
+ | `nearhost up [project...]` | Serve projects without the full-screen view |
80
+ | `nearhost doctor` | Check ports, the certificate authority, the hosts block and server access |
81
+ | `nearhost trust` / `untrust` | Add or remove the local certificate authority in the system trust store |
82
+ | `nearhost hosts clean` | Remove the Nearhost block from `/etc/hosts` |
83
+
84
+ Every command takes `--help`.
85
+
86
+ ## How it compares
87
+
88
+ Nearhost serves your own machines to your own browser. To show work to someone else, use a public tunnel service instead.
89
+
90
+ - **`ssh -L` by hand** gives you the same OpenSSH forwards, typed per port and retyped after every dropped connection, with no hostname and no certificate.
91
+ - **Editor port forwarding** gives you `localhost:port` URLs while the editor window stays open. Nearhost runs in a terminal, and each project keeps the same HTTPS name every day.
92
+ - **A VPN or mesh network** usually needs an agent on every machine and a dev server that listens beyond `localhost`.
93
+ - **A public tunnel service** sends your traffic through someone else's relay to a public URL, usually behind an account.
94
+
95
+ ## How this package works
96
+
97
+ `@nearhost/cli` holds a small Node launcher. The Go binary comes in a platform package, `@nearhost/cli-darwin-arm64`, `@nearhost/cli-darwin-x64`, `@nearhost/cli-linux-arm64` or `@nearhost/cli-linux-x64`, and npm installs only the one that matches your machine. No install script runs, so `--ignore-scripts` works. Each binary matches the one on the [GitHub release](https://github.com/nearhost/nearhost/releases) byte for byte, and versions published by the release workflow carry npm provenance.
17
98
 
18
- On Linux, Nearhost needs permission to bind ports 80 and 443. `nearhost doctor` tells you how to grant it.
99
+ ## Licence
19
100
 
20
- Read the [docs](https://nearhost.dev/docs/) for the rest. The source is at [github.com/nearhost/nearhost](https://github.com/nearhost/nearhost).
101
+ MIT. The source lives at [github.com/nearhost/nearhost](https://github.com/nearhost/nearhost), and the documentation at [nearhost.dev/docs](https://nearhost.dev/docs/getting-started/introduction/).
package/package.json CHANGED
@@ -1,14 +1,29 @@
1
1
  {
2
2
  "name": "@nearhost/cli",
3
- "version": "0.4.0",
4
- "description": "Reach local and remote development servers at https://<name>.test",
3
+ "version": "0.5.0",
4
+ "description": "Open dev servers on your other machines at trusted https://<name>.test addresses over your own SSH. A terminal app for macOS and Linux.",
5
5
  "keywords": [
6
6
  "dev server",
7
+ "development server",
8
+ "localhost",
7
9
  "https",
10
+ "local https",
11
+ "ssl certificate",
12
+ "certificate authority",
8
13
  "ssh",
9
- "tunnel",
10
- "localhost",
11
- "certificate"
14
+ "ssh tunnel",
15
+ "port forwarding",
16
+ "remote development",
17
+ "reverse proxy",
18
+ ".test domain",
19
+ "hot reload",
20
+ "websocket",
21
+ "vite",
22
+ "docker compose",
23
+ "tui",
24
+ "cli",
25
+ "macos",
26
+ "linux"
12
27
  ],
13
28
  "homepage": "https://nearhost.dev",
14
29
  "bugs": "https://github.com/nearhost/nearhost/issues",
@@ -18,6 +33,7 @@
18
33
  "directory": "npm/cli"
19
34
  },
20
35
  "license": "MIT",
36
+ "author": "Nearhost (https://nearhost.dev)",
21
37
  "bin": {
22
38
  "nearhost": "bin/nearhost.js"
23
39
  },
@@ -28,9 +44,9 @@
28
44
  "node": ">=18"
29
45
  },
30
46
  "optionalDependencies": {
31
- "@nearhost/cli-darwin-x64": "0.4.0",
32
- "@nearhost/cli-darwin-arm64": "0.4.0",
33
- "@nearhost/cli-linux-x64": "0.4.0",
34
- "@nearhost/cli-linux-arm64": "0.4.0"
47
+ "@nearhost/cli-darwin-x64": "0.5.0",
48
+ "@nearhost/cli-darwin-arm64": "0.5.0",
49
+ "@nearhost/cli-linux-x64": "0.5.0",
50
+ "@nearhost/cli-linux-arm64": "0.5.0"
35
51
  }
36
52
  }