@nearhost/cli 0.0.0-stage → 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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Edward Coleridge Smith
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,101 @@
1
- # Temporary Holding Version
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
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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`.
6
+
7
+ ```sh
8
+ npx @nearhost/cli
9
+ ```
10
+
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:
39
+
40
+ ```sh
41
+ npm install -g @nearhost/cli
42
+ nearhost
43
+ ```
44
+
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.
98
+
99
+ ## Licence
100
+
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/).
@@ -0,0 +1,46 @@
1
+ #!/usr/bin/env node
2
+ // Runs the nearhost binary from the platform package npm installed next to
3
+ // this one. Each @nearhost/cli-<os>-<arch> package declares os and cpu, so
4
+ // npm installs only the one that matches this machine.
5
+ 'use strict';
6
+
7
+ const { spawn } = require('node:child_process');
8
+
9
+ const pkg = `@nearhost/cli-${process.platform}-${process.arch}`;
10
+
11
+ let bin;
12
+ try {
13
+ bin = require.resolve(`${pkg}/bin/nearhost`);
14
+ } catch {
15
+ const supported = ['darwin', 'linux'].includes(process.platform) && ['x64', 'arm64'].includes(process.arch);
16
+ console.error(
17
+ supported
18
+ ? `nearhost: ${pkg} is not installed. It is an optional dependency of @nearhost/cli; reinstall without --no-optional or --omit=optional.`
19
+ : `nearhost: there is no build for ${process.platform} on ${process.arch}. Nearhost runs on macOS and Linux, on x64 and arm64.`,
20
+ );
21
+ process.exit(1);
22
+ }
23
+
24
+ const child = spawn(bin, process.argv.slice(2), { stdio: 'inherit' });
25
+
26
+ // Ctrl-C and a closing terminal reach nearhost directly, as they reach every
27
+ // process in the foreground group; passing them on as well would count as a
28
+ // second signal, which makes `nearhost up` cut its shutdown short. A SIGTERM
29
+ // is sent to this process alone, so it is passed on.
30
+ process.on('SIGINT', () => {});
31
+ process.on('SIGHUP', () => {});
32
+ process.on('SIGTERM', () => child.kill('SIGTERM'));
33
+
34
+ child.on('error', (err) => {
35
+ console.error(`nearhost: could not run ${bin}: ${err.message}`);
36
+ process.exit(1);
37
+ });
38
+
39
+ child.on('exit', (code, signal) => {
40
+ if (signal) {
41
+ process.removeAllListeners(signal);
42
+ process.kill(process.pid, signal);
43
+ return;
44
+ }
45
+ process.exit(code);
46
+ });
package/package.json CHANGED
@@ -1,6 +1,52 @@
1
1
  {
2
2
  "name": "@nearhost/cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
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
+ "keywords": [
6
+ "dev server",
7
+ "development server",
8
+ "localhost",
9
+ "https",
10
+ "local https",
11
+ "ssl certificate",
12
+ "certificate authority",
13
+ "ssh",
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"
27
+ ],
28
+ "homepage": "https://nearhost.dev",
29
+ "bugs": "https://github.com/nearhost/nearhost/issues",
30
+ "repository": {
31
+ "type": "git",
32
+ "url": "git+https://github.com/nearhost/nearhost.git",
33
+ "directory": "npm/cli"
34
+ },
35
+ "license": "MIT",
36
+ "author": "Nearhost (https://nearhost.dev)",
37
+ "bin": {
38
+ "nearhost": "bin/nearhost.js"
39
+ },
40
+ "files": [
41
+ "bin"
42
+ ],
43
+ "engines": {
44
+ "node": ">=18"
45
+ },
46
+ "optionalDependencies": {
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"
51
+ }
52
+ }