@remotehost/cli 1.0.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.md ADDED
@@ -0,0 +1,3 @@
1
+ © RemoteHost, Inc. All rights reserved. Use is subject to RemoteHost's [Terms of Service](https://remotehost.ai/terms).
2
+
3
+ The open-source packages compiled into this software are licensed separately; their licences and copyright notices are reproduced in [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md).
package/README.md ADDED
@@ -0,0 +1,118 @@
1
+ # RemoteHost CLI
2
+
3
+ Create sandboxes, attach to them, and manage a fleet without leaving the
4
+ terminal.
5
+
6
+ ```sh
7
+ npm i -g @remotehost/cli
8
+ remote login
9
+ ```
10
+
11
+ The command is `remote`.
12
+
13
+ ## Getting started
14
+
15
+ ```sh
16
+ remote claude # a sandbox with Claude Code, opened in this terminal
17
+ remote ls # what is running
18
+ remote attach <name> # a shell in one
19
+ remote attach --agent <name> # back to its Claude Code (or Codex)
20
+ remote sleep <name> # stop paying for it, keep the disk
21
+ ```
22
+
23
+ `remote claude` and `remote codex` make the sandbox and open the agent in
24
+ this terminal; Ctrl-G detaches and leaves it running. If the agent cannot be
25
+ opened, the command says why and offers to remove the sandbox it made.
26
+ `remote new claude` only makes the sandbox.
27
+
28
+ Run `remote` on its own to open the TUI, which is the interactive version of all
29
+ of the above.
30
+
31
+ In the sandbox table, **Space** toggles the highlighted row, **Shift+Up/Down**
32
+ selects a range, **Ctrl+A** selects all matching rows, and **a** toggles all.
33
+ **Esc** clears the selection. Use **/** to filter; Space and **a** type into
34
+ the filter while it is focused. Selections follow sandbox IDs across refreshes
35
+ and clear when rows are filtered out or you leave the project.
36
+
37
+ With rows selected, **Enter**, **s**, or **Ctrl+G** opens actions for the selection:
38
+ Sleep, Wake, Renew, and Delete. Each action shows its eligible sandbox count;
39
+ for example, Sleep applies to running persistent sandboxes and Renew applies to
40
+ running ephemeral sandboxes. Delete lists its targets and requires **y** to
41
+ confirm. Results report successes and failures, leaving failed rows selected
42
+ for retry.
43
+
44
+ Type while the command menu is open to filter its actions. Use **Up/Down** to
45
+ move through matches, **Enter** to run, **Backspace** to edit, and **Esc** or
46
+ **Ctrl+G** to close. The filter resets each time the menu opens.
47
+
48
+ ## Scripting
49
+
50
+ Every command that reports data takes `--json`, which is the flag to reach for
51
+ from a script or an SDK rather than parsing the table:
52
+
53
+ ```sh
54
+ remote ls --json | jq '.[] | select(.status == "running") | .name'
55
+ remote new claude --name checkout --json
56
+ ```
57
+
58
+ The contract is narrow on purpose:
59
+
60
+ - **stdout** carries exactly one JSON document, or nothing. A list command emits
61
+ an array — empty when there is nothing, never the words "No sandboxes found."
62
+ A single-subject command emits an object.
63
+ - **stderr** carries every diagnostic, including a `{"error": {...}}` document
64
+ when a command fails. Nothing that is not the result reaches stdout.
65
+ - **the exit code** is 0 on success and 1 on failure, so you can decide which
66
+ stream to parse before parsing it.
67
+
68
+ The tab-separated output is unchanged and is not going away. It is a good thing
69
+ to read and a poor thing to parse: values contain spaces, and every number
70
+ arrives as text with its unit attached.
71
+
72
+ ## Authentication
73
+
74
+ `remote login` opens a browser and approves this machine. For CI and agents,
75
+ create a key with `remote keys create` and set `REMOTEHOST_TOKEN` instead.
76
+
77
+ For an MCP agent that orchestrates sessions across your projects and
78
+ organizations, `remote mcp setup --personal` prints a configuration with an
79
+ expiring read/send token. Add `--approve` to allow tool-approval answers or
80
+ `--wake` to wake existing sandboxes. Use `--read-only` for observation only.
81
+ `remote mcp tokens` lists your tokens; `remote mcp revoke <id>` revokes one.
82
+ Personal tokens require the updated API and agent-token database migration.
83
+ They do not grant shell/file access or sandbox deletion. See
84
+ [agent sessions](../../docs/agent-sessions.md) for rollout status and native
85
+ terminal limitations.
86
+
87
+ ## Configuration
88
+
89
+ | variable | what it does |
90
+ | --- | --- |
91
+ | `REMOTEHOST_TOKEN` | API key, for non-interactive use |
92
+ | `REMOTEHOST_API_URL` | point the CLI at a different API |
93
+ | `REMOTEHOST_CONFIG_DIR` | where the login session is stored |
94
+
95
+ ## Requirements
96
+
97
+ Node.js 22 or newer. No other runtime dependencies — the package is a single
98
+ bundled file.
99
+
100
+ Because it is bundled, the open-source packages it depends on are compiled into
101
+ that file rather than installed beside it. Their licences and copyright notices
102
+ are reproduced in full in `THIRD-PARTY-NOTICES.md`, which ships with the
103
+ package.
104
+
105
+ ## Issues and docs
106
+
107
+ - Issues: https://github.com/remotehostai/cli/issues
108
+ - Docs: https://remotehost.ai/docs
109
+
110
+ ## Local development
111
+
112
+ `remote-staging` runs `packages/cli/src/index-staging.ts` from the local root
113
+ checkout through `tsx`, against `https://api-staging.remotehost.ai`. CLI source
114
+ edits take effect on the next launch without copying a bundle. Staging keeps its
115
+ own login session. `remote-staging-update` rebuilds local workspace dependencies.
116
+
117
+ `remote` is the npm registry installation of `@remotehost/cli`; keep it separate
118
+ from local builds and workspace links.