cli-setu 0.3.1 → 0.3.3

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/README.md CHANGED
@@ -1,40 +1,44 @@
1
- # cli-setu
2
-
3
- Bridge your terminal to your phone. Run Claude Code, Codex, or any plain shell on your laptop, and approve prompts, type, and watch the live output from the [cli-setu](https://clisetu.com) app on your phone.
4
-
5
- ## Install
6
-
7
- ```bash
8
- npm install -g cli-setu
9
- ```
10
-
11
- ## Usage
12
-
13
- ```bash
14
- cli-setu # bridges the current folder as a plain shell session
15
- cli-setu --cli claude # same, but runs Claude Code inside the bridged session
16
- cli-setu --cli codex # or Codex
17
- ```
18
-
19
- The first time you run it, `cli-setu` prints a QR code (and an 8-digit fallback code) - scan it with the cli-setu app to pair this computer and start watching the session live.
20
-
21
- Once paired, running `cli-setu` in any folder just works - no QR code needed again, unless this is a device you haven't paired before.
22
-
23
- ## Other commands
24
-
25
- ```bash
26
- cli-setu pair # pair this computer, without starting a session
27
- cli-setu status # show pairing status and any sessions currently running
28
- cli-setu stop # stop a running session
29
- cli-setu --update # check for and install the latest version
30
- cli-setu --version # print the installed version
31
- cli-setu --help # show all commands
32
- ```
33
-
34
- ## How it works
35
-
36
- `cli-setu` spawns your real terminal (or Claude Code/Codex) inside a PTY, same as any terminal emulator. Every byte it produces streams live to the cli-setu app over a secure relay; anything you type on the phone writes back into that same PTY, exactly like a local keystroke. Permission prompts (file edits, shell commands, etc.) are detected and relayed as structured approve/reject cards instead of raw text, when the adapter for your CLI supports it.
37
-
38
- ## License
39
-
40
- MIT
1
+ # cli-setu
2
+
3
+ Bridge your terminal to your phone. Run Claude Code, Codex, or any plain shell on your laptop, and approve prompts, type, and watch the live output from the [cli-setu](https://clisetu.com) app on your phone.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install -g cli-setu
9
+ ```
10
+
11
+ ## Usage
12
+
13
+ Pairing and starting a session are two separate steps:
14
+
15
+ ```bash
16
+ cli-setu pair # pair this computer with your phone - does NOT start a session
17
+ cli-setu session # bridge the current folder as a plain shell session
18
+ cli-setu session --cli claude # same, but runs Claude Code inside the bridged session
19
+ cli-setu session --cli codex # or Codex
20
+ ```
21
+
22
+ The first time you run `cli-setu pair`, it prints a QR code (and an 8-character fallback code) - scan it with the cli-setu app to pair this computer. Pairing alone never opens a terminal session or starts any process - run `cli-setu session` afterward, in whichever folder you want to bridge, whenever you're ready.
23
+
24
+ Once paired, `cli-setu session` in any folder just works - no QR code needed again, unless this is a device you haven't paired before. A device can only ever run a limited number of live sessions at once, and cli-setu refuses to start a second session for the same project folder while one is already running there.
25
+
26
+ ## Other commands
27
+
28
+ ```bash
29
+ cli-setu status # show pairing status and any sessions currently running
30
+ cli-setu stop # stop every session running on this computer
31
+ cli-setu stop <sessionId> # stop just one session - see `cli-setu status` for the exact id
32
+ cli-setu unpair # unpair this computer (asks for confirmation)
33
+ cli-setu --update # check for and install the latest version
34
+ cli-setu --version, -v # print the installed version
35
+ cli-setu --help, -h # show all commands
36
+ ```
37
+
38
+ ## How it works
39
+
40
+ `cli-setu` spawns your real terminal (or Claude Code/Codex) inside a PTY, same as any terminal emulator. Every byte it produces streams live to the cli-setu app over a secure relay; anything you type on the phone writes back into that same PTY, exactly like a local keystroke. Permission prompts (file edits, shell commands, etc.) are detected and relayed as structured approve/reject cards instead of raw text, when the adapter for your CLI supports it.
41
+
42
+ ## License
43
+
44
+ MIT
package/bin/setu.js CHANGED
@@ -1,150 +1,173 @@
1
1
  #!/usr/bin/env node
2
- // Command dispatcher for the `cli-setu` CLI. Kept deliberately thin - each
3
- // real subcommand's logic lives in src/, this file only parses argv and
4
- // calls the right one.
5
- //
6
- // TEMPORARY: defaults to the DEV server (dev-api.clisetu.com), not
7
- // production, because only dev-api is live right now. MUST switch back to
8
- // https://api.clisetu.com and republish before announcing this package to
9
- // real users as "production ready" - see clisetuapp/backend's deployment
10
- // guide for when production actually goes live.
11
- const AUTH_SERVER = process.env.CLI_SETU_SERVER || 'https://dev-api.clisetu.com';
12
- const AUTH_SERVER_PUBLIC = process.env.CLI_SETU_SERVER_PUBLIC || AUTH_SERVER;
13
-
14
- // Real bug found by testing: this used to switch on process.argv[2]
15
- // directly against the subcommand list (pair/status/stop), with any
16
- // other value (including a real --flag, e.g. `cli-setu --cli claude`)
17
- // falling through to "Unknown command" and exiting immediately - the
18
- // whole multi-CLI feature (claude/codex/shell adapters) was unreachable
19
- // through the real `cli-setu` command this entire time, only ever testable
20
- // by calling node src/supervisor.js --cli claude directly. Flags
21
- // (anything starting with "-") are no longer mistaken for subcommand
22
- // names - they're checked first, and anything left over (bare `cli-setu`, or
23
- // `cli-setu --cli claude`/other flags meant for the bridged session itself)
24
- // falls through to the same "watch this session" path as before, which
25
- // still parses --cli on its own further down the line (supervisor.js) -
26
- // this dispatcher doesn't need to understand every flag supervisor.js
27
- // accepts, only recognize that a leading "-" means "not a subcommand."
28
- const args = process.argv.slice(2);
29
- const firstArg = args[0];
30
- const isSubcommand = firstArg && !firstArg.startsWith('-');
31
-
32
- // Real bug found by testing: a genuinely unrecognized flag like `-rfesfd`
33
- // or `-g` (a typo, not meant for supervisor.js at all) also starts with
34
- // "-", so it fell through the isSubcommand check above straight into the
35
- // bare-`cli-setu` session-watching path below - silently pairing/starting
36
- // a real session and generating a QR code instead of telling the user
37
- // their command doesn't exist. supervisor.js only ever actually reads
38
- // `--cli <name>` out of argv (confirmed by reading it directly - the
39
- // `[workingDir]` mentioned in its own old comment is dead, WORKING_DIR is
40
- // just process.cwd()) - every other `-`-prefixed flag is unrecognized by
41
- // definition, same as an unrecognized subcommand already is below.
42
- const KNOWN_FLAGS = new Set(['--version', '-v', '--help', '-h', '--update', '--cli']);
43
- const hasUnknownFlag = args.some((a) => a.startsWith('-') && !KNOWN_FLAGS.has(a));
44
-
45
- async function main() {
46
- if (hasUnknownFlag) {
47
- const bad = args.find((a) => a.startsWith('-') && !KNOWN_FLAGS.has(a));
48
- console.error(`[cli-setu] Unknown option: ${bad}`);
49
- console.error('[cli-setu] For more info, run: cli-setu --help');
50
- process.exit(1);
51
- }
52
-
53
- if (args.includes('--version') || args.includes('-v')) {
54
- console.log(require('../package.json').version);
55
- return;
56
- }
57
-
58
- if (args.includes('--help') || args.includes('-h')) {
59
- printHelp();
60
- return;
61
- }
62
-
63
- if (args.includes('--update')) {
64
- const { update } = require('../src/update');
65
- await update();
66
- return;
67
- }
68
-
69
- if (isSubcommand) {
70
- switch (firstArg) {
71
- case 'pair': {
72
- // Real product ask (PM report): a first-time user had to run
73
- // `cli-setu pair` then separately `cli-setu` to actually start a
74
- // session - two commands where one would do, and the phone had
75
- // nothing to show (no session yet) right after pairing. Matches
76
- // bare `cli-setu`'s own already-correct behavior below: pair (if
77
- // needed), then immediately start watching THIS folder as a
78
- // session, same single-step flow either way now.
79
- const { pair } = require('../src/pair');
80
- await pair(AUTH_SERVER, AUTH_SERVER_PUBLIC);
81
- require('../src/supervisor');
82
- return;
83
- }
84
- case 'status': {
85
- const { status } = require('../src/status');
86
- await status(AUTH_SERVER);
87
- return;
88
- }
89
- case 'stop': {
90
- const { stop } = require('../src/stop');
91
- // args[1] (optional) - a specific sessionId to stop, copied from
92
- // `cli-setu status`'s own output. Omitted stops every session on
93
- // this computer, unchanged from before.
94
- await stop(args[1]);
95
- return;
96
- }
97
- case 'unpair': {
98
- const { unpair } = require('../src/unpair');
99
- await unpair(AUTH_SERVER);
100
- return;
101
- }
102
- default:
103
- console.error(`[cli-setu] Unknown command: ${firstArg}`);
104
- printHelp();
105
- process.exit(1);
106
- }
107
- }
108
-
109
- // Bare `cli-setu` (or `cli-setu --cli <name>`, `cli-setu --cli <name> <workingDir>`,
110
- // etc. - real flags meant for the bridged session itself, parsed by
111
- // supervisor.js) - watch the current directory as a session. Real
112
- // product requirement: a brand-new user should be able to run just
113
- // `cli-setu` (no separate `cli-setu pair` step to discover first) and see the
114
- // QR/8-digit code immediately, the same "first run pairs AND starts
115
- // watching this session in one step" behavior the original
116
- // proof-of-concept had. Only pairs if not already paired - an
117
- // already-paired computer skips straight to watching, unchanged.
118
- const { readConfig } = require('../src/config');
119
- const config = readConfig();
120
- if (!config || !config.deviceToken) {
121
- const { pair } = require('../src/pair');
122
- await pair(AUTH_SERVER, AUTH_SERVER_PUBLIC);
123
- }
124
- require('../src/supervisor');
125
- }
126
-
127
- function printHelp() {
128
- console.log(`[cli-setu] Bridge your terminal to your phone.
129
-
130
- Usage:
131
- cli-setu Watch this folder as a session (pairs first if needed)
132
- cli-setu --cli <name> Same, but run a specific CLI inside the bridged
133
- session instead of the default plain shell
134
- (e.g. --cli claude, --cli codex)
135
- cli-setu pair Pair this computer with your phone, then watch
136
- this folder as a session (same as bare cli-setu)
137
- cli-setu status Show pairing status and any sessions running now
138
- cli-setu stop Stop every session running on this computer
139
- cli-setu stop <sessionId> Stop just one session (see \`cli-setu status\`
140
- for the exact id to use)
141
- cli-setu unpair Unpair this computer (asks for confirmation)
142
- cli-setu --version, -v Print the installed version
143
- cli-setu --update Check for and install the latest version
144
- cli-setu --help, -h Show this help`);
145
- }
146
-
147
- main().catch((err) => {
148
- console.error('[cli-setu] Error:', err.message);
149
- process.exit(1);
150
- });
2
+ // Command dispatcher for the `cli-setu` CLI. Kept deliberately thin - each
3
+ // real subcommand's logic lives in src/, this file only parses argv and
4
+ // calls the right one.
5
+ //
6
+ // TEMPORARY: defaults to the DEV server (dev-api.clisetu.com), not
7
+ // production, because only dev-api is live right now. MUST switch back to
8
+ // https://api.clisetu.com and republish before announcing this package to
9
+ // real users as "production ready" - see clisetuapp/backend's deployment
10
+ // guide for when production actually goes live.
11
+ const AUTH_SERVER = process.env.CLI_SETU_SERVER || 'https://dev-api.clisetu.com';
12
+ const AUTH_SERVER_PUBLIC = process.env.CLI_SETU_SERVER_PUBLIC || AUTH_SERVER;
13
+
14
+ // SETU-001/018 (PM brief, 2026-10-25): pairing and session creation are
15
+ // now two distinct lifecycle operations, never bundled. Real product gap
16
+ // this fixes: a prior revision of this file made `cli-setu pair` (and bare
17
+ // `cli-setu`) ALSO immediately start watching the current folder as a
18
+ // live terminal session - meaning simply pairing a laptop silently created
19
+ // a real PTY-backed session, registered it with the backend, and showed up
20
+ // as "live" on the phone, with no explicit ask from the user. `cli-setu
21
+ // pair` now ONLY pairs. `cli-setu session` is the one and only way to
22
+ // start watching a folder as a session (optionally `--cli claude`/
23
+ // `--cli codex` to bridge a specific CLI instead of a plain shell). Bare
24
+ // `cli-setu` (no subcommand) shows help instead of guessing which of the
25
+ // two the user meant.
26
+ //
27
+ // Real bug found by testing (kept from the previous revision of this
28
+ // comment): this used to switch on process.argv[2] directly against the
29
+ // subcommand list, with any other value (including a real --flag) falling
30
+ // through to "Unknown command" - flags are checked first here so a known
31
+ // flag never gets mistaken for an unrecognized subcommand.
32
+ const args = process.argv.slice(2);
33
+ const firstArg = args[0];
34
+ const isSubcommand = firstArg && !firstArg.startsWith('-');
35
+
36
+ // Real bug found by testing: a genuinely unrecognized flag like `-rfesfd`
37
+ // or `-g` (a typo) also starts with "-" - without this check it fell
38
+ // through isSubcommand straight into whatever the fallback path was,
39
+ // silently doing something the user never asked for instead of telling
40
+ // them their command doesn't exist. supervisor.js only ever actually
41
+ // reads `--cli <name>` out of argv (confirmed by reading it directly) -
42
+ // every other `-`-prefixed flag is unrecognized by definition.
43
+ const KNOWN_FLAGS = new Set(['--version', '-v', '--help', '-h', '--update', '--cli']);
44
+ const hasUnknownFlag = args.some((a) => a.startsWith('-') && !KNOWN_FLAGS.has(a));
45
+
46
+ async function main() {
47
+ if (hasUnknownFlag) {
48
+ const bad = args.find((a) => a.startsWith('-') && !KNOWN_FLAGS.has(a));
49
+ console.error(`[cli-setu] Unknown option: ${bad}`);
50
+ console.error('[cli-setu] For more info, run: cli-setu --help');
51
+ process.exit(1);
52
+ }
53
+
54
+ if (args.includes('--version') || args.includes('-v')) {
55
+ console.log(require('../package.json').version);
56
+ return;
57
+ }
58
+
59
+ if (args.includes('--help') || args.includes('-h')) {
60
+ printHelp();
61
+ return;
62
+ }
63
+
64
+ if (args.includes('--update')) {
65
+ const { update } = require('../src/update');
66
+ await update();
67
+ return;
68
+ }
69
+
70
+ if (isSubcommand) {
71
+ switch (firstArg) {
72
+ case 'pair': {
73
+ // SETU-001: pairing ONLY pairs - it never starts a session anymore
74
+ // (see this file's top-of-file comment for the real gap this
75
+ // fixes). An already-paired device gets pair.js's own existing
76
+ // "already paired" message and returns, same as before - the only
77
+ // change is that this branch no longer follows up with
78
+ // require('../src/supervisor').
79
+ const { pair } = require('../src/pair');
80
+ // Real bug found by review, fixed before ever shipping: this used
81
+ // to print its own "Device paired successfully..." line
82
+ // UNCONDITIONALLY after calling pair(), even for an already-paired
83
+ // device - confirmed live, it printed BOTH pair.js's own
84
+ // "already paired, run cli-setu session" hint AND this generic
85
+ // success line back to back, a confusing duplicate (and the
86
+ // success line was also just plain wrong in that case - nothing
87
+ // was actually paired this run). alreadyPaired (now returned by
88
+ // pair() itself) means this success line only ever prints for a
89
+ // GENUINELY new pairing.
90
+ const { alreadyPaired } = await pair(AUTH_SERVER, AUTH_SERVER_PUBLIC);
91
+ if (!alreadyPaired) {
92
+ console.log('[cli-setu] Device paired successfully. To start a terminal session, run: cli-setu session');
93
+ }
94
+ return;
95
+ }
96
+ case 'session': {
97
+ // SETU-001/006: `cli-setu session` (optionally `--cli claude` /
98
+ // `--cli codex`) is now the ONLY way to start watching a folder as
99
+ // a live session. supervisor.js itself already refuses to run at
100
+ // all (clear error, not a crash) if this device isn't paired yet -
101
+ // see its own top-of-file guard - so this branch doesn't need to
102
+ // duplicate that check here; it just needs to never silently pair
103
+ // on the user's behalf first, unlike the old bare-`cli-setu` path.
104
+ require('../src/supervisor');
105
+ return;
106
+ }
107
+ case 'status': {
108
+ const { status } = require('../src/status');
109
+ await status(AUTH_SERVER);
110
+ return;
111
+ }
112
+ case 'stop': {
113
+ const { stop } = require('../src/stop');
114
+ // args[1] (optional) - a specific sessionId to stop, copied from
115
+ // `cli-setu status`'s own output. Omitted stops every session on
116
+ // this computer, unchanged from before.
117
+ await stop(args[1]);
118
+ return;
119
+ }
120
+ case 'unpair': {
121
+ const { unpair } = require('../src/unpair');
122
+ await unpair(AUTH_SERVER);
123
+ return;
124
+ }
125
+ default:
126
+ console.error(`[cli-setu] Unknown command: ${firstArg}`);
127
+ printHelp();
128
+ process.exit(1);
129
+ }
130
+ }
131
+
132
+ // SETU-001/018: bare `cli-setu` (no subcommand) NO LONGER auto-pairs or
133
+ // auto-starts a session - it used to do both in one step (a real
134
+ // product decision this brief explicitly reverses: pairing and session
135
+ // creation must be two distinct, explicitly-requested operations, never
136
+ // bundled or guessed). Show help instead, same as the project's other
137
+ // "don't guess, tell the user what to type" safe-help behavior
138
+ // (supervisor.js's own unpaired-device message follows the same shape).
139
+ printHelp();
140
+ const { readConfig } = require('../src/config');
141
+ const config = readConfig();
142
+ if (!config || !config.deviceToken) {
143
+ console.log('\n[cli-setu] This computer isn\'t paired yet. Run `cli-setu pair` to get started.');
144
+ } else {
145
+ console.log('\n[cli-setu] Already paired. Run `cli-setu session` to start a terminal session.');
146
+ }
147
+ }
148
+
149
+ function printHelp() {
150
+ console.log(`[cli-setu] Bridge your terminal to your phone.
151
+
152
+ Usage:
153
+ cli-setu pair Pair this computer with your phone (does NOT
154
+ start a session)
155
+ cli-setu session Start watching this folder as a live
156
+ terminal session (must be paired first)
157
+ cli-setu session --cli <name> Same, but run a specific CLI inside the
158
+ bridged session instead of the default plain
159
+ shell (e.g. --cli claude, --cli codex)
160
+ cli-setu status Show pairing status and any sessions running now
161
+ cli-setu stop Stop every session running on this computer
162
+ cli-setu stop <sessionId> Stop just one session (see \`cli-setu status\`
163
+ for the exact id to use)
164
+ cli-setu unpair Unpair this computer (asks for confirmation)
165
+ cli-setu --version, -v Print the installed version
166
+ cli-setu --update Check for and install the latest version
167
+ cli-setu --help, -h Show this help`);
168
+ }
169
+
170
+ main().catch((err) => {
171
+ console.error('[cli-setu] Error:', err.message);
172
+ process.exit(1);
173
+ });
package/package.json CHANGED
@@ -1,12 +1,15 @@
1
1
  {
2
2
  "name": "cli-setu",
3
- "version": "0.3.1",
3
+ "version": "0.3.3",
4
4
  "description": "Bridge your terminal to your phone — run and approve Claude Code, Codex CLI and other AI coding agents from anywhere.",
5
5
  "type": "commonjs",
6
6
  "bin": {
7
7
  "cli-setu": "bin/setu.js"
8
8
  },
9
9
  "main": "src/config.js",
10
+ "scripts": {
11
+ "test": "node test/run-all.js"
12
+ },
10
13
  "engines": {
11
14
  "node": ">=18"
12
15
  },