-
Notifications
You must be signed in to change notification settings - Fork 4
Expand file tree
/
Copy pathcli.ts
More file actions
13332 lines (12792 loc) · 396 KB
/
Copy pathcli.ts
File metadata and controls
13332 lines (12792 loc) · 396 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#!/usr/bin/env node
import { Buffer } from "node:buffer";
import { spawn, spawnSync } from "node:child_process";
import fs from "node:fs";
import net from "node:net";
import path from "node:path";
import { pathToFileURL } from "node:url";
import YAML from "yaml";
import {
CURSOR_CLOUD_HELP,
CursorCloudUsageError,
runCursorCloud,
} from "./cursorCloud";
import { resolveMachineAdeLayout } from "./services/projects/machineLayout";
import {
findAdeManagedWorktreeRoot,
realpathIfExists,
} from "./services/projects/projectRoots";
import {
JsonRpcError,
JsonRpcErrorCode,
startJsonRpcServer,
type JsonRpcHandler,
type JsonRpcId,
type JsonRpcRequest,
type JsonRpcTransport,
} from "./jsonrpc";
import { isAdeMcpNamedPipePath } from "../../desktop/src/shared/adeMcpIpc";
import {
isLaunchProfile,
isTrackedCliPermissionMode,
LAUNCH_PROFILE_TITLE,
validateLaunchProfilePermissionMode,
type LaunchProfile,
} from "../../desktop/src/shared/cliLaunch";
import type {
SyncMobileProjectSummary,
SyncProjectSwitchRequestPayload,
SyncProjectSwitchResultPayload,
} from "../../desktop/src/shared/types/sync";
type JsonObject = Record<string, unknown>;
type GlobalOptions = {
projectRoot: string | null;
workspaceRoot: string | null;
role: "cto" | "orchestrator" | "agent" | "external" | "evaluator";
headless: boolean;
requireSocket: boolean;
pretty: boolean;
text: boolean;
timeoutMs: number;
};
type ParsedCli = {
options: GlobalOptions;
command: string[];
};
type InvocationStep = {
key: string;
method: string;
params?: JsonObject | ((values: JsonObject) => JsonObject);
unwrapToolResult?: boolean;
optional?: boolean;
};
type FormatterId =
| "status"
| "doctor"
| "auth"
| "projects-list"
| "linear-quick-view"
| "lanes"
| "lane-detail"
| "git-status"
| "diff-summary"
| "file-read"
| "files-tree"
| "files-search"
| "prs-list"
| "pr-detail"
| "pr-checks"
| "pr-comments"
| "mission-list"
| "mission-detail"
| "mission-runs"
| "mission-graph"
| "mission-watch"
| "run-defs"
| "run-runtime"
| "chat-list"
| "tests-runs"
| "proof-list"
| "ios-sim-status"
| "ios-sim-devices"
| "ios-sim-apps"
| "ios-sim-stream"
| "ios-sim-snapshot"
| "ios-sim-selection"
| "ios-sim-preview"
| "app-control-status"
| "app-control-snapshot"
| "app-control-selection"
| "browser-status"
| "macos-vm-status"
| "macos-vm-share-policy"
| "macos-vm-guide"
| "macos-vm-capture"
| "macos-vm-selection"
| "terminal-list"
| "terminal-read"
| "actions-list"
| "action-result"
| "automation-run-detail";
type CliPlan =
| { kind: "help"; text: string }
| {
kind: "execute";
label: string;
steps: InvocationStep[];
visualizer?: "lanes";
summary?: "status" | "doctor" | "auth";
formatter?: FormatterId;
preferHeadless?: boolean;
}
| { kind: "ade-code"; rest: string[] }
| { kind: "desktop"; rest: string[] }
| { kind: "runtime"; rest: string[] }
| { kind: "serve"; rest: string[] }
| { kind: "rpc-stdio"; rest: string[] }
| { kind: "init"; targetPath: string | null }
| { kind: "cursor-cloud"; rest: string[] }
| { kind: "mcp" };
type CliConnection = {
mode: "desktop-socket" | "runtime-socket" | "headless";
projectRoot: string;
workspaceRoot: string;
socketPath: string;
request: (method: string, params?: JsonObject) => Promise<unknown>;
close: () => Promise<void> | void;
};
class CliUsageError extends Error {}
class CliToolError extends Error {
details: unknown;
constructor(message: string, details: unknown) {
super(message);
this.details = details;
}
}
class CliExecutionError extends Error {
details: JsonObject;
constructor(message: string, details: JsonObject) {
super(message);
this.details = details;
}
}
type ReadinessCheck = {
ready: boolean;
status: "ready" | "warning" | "missing" | "unavailable";
message: string;
nextAction?: string;
details?: JsonObject;
};
declare const __ADE_VERSION__: string | undefined;
const BUNDLED_VERSION =
typeof __ADE_VERSION__ === "string" ? __ADE_VERSION__.trim() : "";
const ENV_VERSION = process.env.ADE_CLI_VERSION?.trim() ?? "";
const VERSION =
BUNDLED_VERSION && BUNDLED_VERSION !== "0.0.0"
? BUNDLED_VERSION
: ENV_VERSION || BUNDLED_VERSION || "0.0.0";
const PROTOCOL_VERSION = "2025-06-18";
const SOURCE_FALLBACK_ENV = "ADE_CLI_SOURCE_FALLBACK_ACTIVE";
const CLI_ENTRY_PATH =
typeof process.argv[1] === "string" ? path.resolve(process.argv[1]) : "";
const CLI_PACKAGE_ROOT = resolveCliPackageRoot(CLI_ENTRY_PATH);
const CLI_DIST_PATH = path.join(CLI_PACKAGE_ROOT, "dist", "cli.cjs");
const COORDINATOR_MCP_TOOL_NAMES = new Set([
"spawn_worker",
"insert_milestone",
"request_specialist",
"delegate_to_subagent",
"delegate_parallel",
"stop_worker",
"send_message",
"message_worker",
"broadcast",
"get_worker_output",
"list_workers",
"report_status",
"report_result",
"report_validation",
"read_mission_status",
"read_mission_state",
"update_mission_state",
"revise_plan",
"update_tool_profiles",
"transfer_lane",
"provision_lane",
"set_current_phase",
"create_task",
"update_task",
"assign_task",
"list_tasks",
"skip_step",
"mark_step_complete",
"mark_step_failed",
"retry_step",
"complete_mission",
"fail_mission",
"get_budget_status",
"request_user_input",
"read_file",
"read_step_output",
"search_files",
"get_project_context",
]);
const WORKER_MISSION_TOOL_CLI_NAMES = new Set([
"get_mission",
"get_run_graph",
"get_worker_states",
"get_timeline",
"get_pending_messages",
"stream_events",
"message_worker",
]);
function resolveCliPackageRoot(entryPath: string): string {
const seen = new Set<string>();
const starts = [entryPath ? path.dirname(entryPath) : null, process.cwd()];
for (const start of starts) {
if (!start) continue;
let cursor = path.resolve(start);
while (!seen.has(cursor)) {
seen.add(cursor);
const packageJson = path.join(cursor, "package.json");
const srcCli = path.join(cursor, "src", "cli.ts");
if (fs.existsSync(packageJson) && fs.existsSync(srcCli)) {
return cursor;
}
const parent = path.dirname(cursor);
if (parent === cursor) break;
cursor = parent;
}
}
return path.resolve(process.cwd(), "apps", "ade-cli");
}
function isSourceCliEntryPath(modulePath: string): boolean {
return /[/\\]src[/\\]cli\.ts$/i.test(modulePath);
}
function isSourceRuntimeInteropError(value: unknown): boolean {
const message =
typeof value === "string"
? value
: value instanceof Error
? value.message
: "";
if (!message.length) return false;
const lower = message.toLowerCase();
return (
lower.includes("__filename is not defined in es module scope") ||
lower.includes("__filename is not defined") ||
lower.includes("__dirname is not defined")
);
}
function formatSpawnFailure(
result: ReturnType<typeof spawnSync>,
fallbackCommand: string,
): string {
if (result.error) {
return result.error.message;
}
const status = typeof result.status === "number" ? result.status : "unknown";
const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
const stdout = typeof result.stdout === "string" ? result.stdout.trim() : "";
const detail = stderr || stdout || "No output captured.";
return `${fallbackCommand} exited with status ${status}: ${detail}`;
}
function latestMtimeMs(root: string): number {
let latest = 0;
let entries: fs.Dirent[];
try {
entries = fs.readdirSync(root, { withFileTypes: true });
} catch {
return latest;
}
for (const entry of entries) {
const fullPath = path.join(root, entry.name);
if (entry.isDirectory()) {
latest = Math.max(latest, latestMtimeMs(fullPath));
continue;
}
if (!entry.isFile()) continue;
try {
latest = Math.max(latest, fs.statSync(fullPath).mtimeMs);
} catch {
// Ignore files that disappear while checking freshness.
}
}
return latest;
}
function isBuiltCliFresh(): boolean {
try {
const distMtime = fs.statSync(CLI_DIST_PATH).mtimeMs;
const sourceMtime = latestMtimeMs(path.join(CLI_PACKAGE_ROOT, "src"));
return distMtime >= sourceMtime;
} catch {
return false;
}
}
function maybeRunBuiltCliFallback(
error: unknown,
argv: string[],
): { stdout: string; stderr: string; exitCode: number } | null {
if (!(error instanceof CliExecutionError)) return null;
if (process.env[SOURCE_FALLBACK_ENV] === "1") return null;
if (!isSourceCliEntryPath(CLI_ENTRY_PATH)) return null;
if (
!isSourceRuntimeInteropError(asString(error.details.cause) ?? error.message)
)
return null;
if (!isBuiltCliFresh()) {
const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
const buildResult = spawnSync(npmCommand, ["run", "build", "--silent"], {
cwd: CLI_PACKAGE_ROOT,
env: process.env,
encoding: "utf8",
});
if (buildResult.error || buildResult.status !== 0 || !isBuiltCliFresh()) {
error.details.nextAction =
"Run `npm --prefix apps/ade-cli run build` and retry the command.";
error.details.fallback = formatSpawnFailure(
buildResult,
"npm run build --silent",
);
return null;
}
}
const rerun = spawnSync(process.execPath, [CLI_DIST_PATH, ...argv], {
cwd: process.cwd(),
env: {
...process.env,
[SOURCE_FALLBACK_ENV]: "1",
},
encoding: "utf8",
});
if (rerun.error) {
error.details.nextAction =
"Run `node apps/ade-cli/dist/cli.cjs ...` directly to inspect the runtime failure.";
error.details.fallback = rerun.error.message;
return null;
}
return {
stdout: typeof rerun.stdout === "string" ? rerun.stdout : "",
stderr: typeof rerun.stderr === "string" ? rerun.stderr : "",
exitCode: rerun.status ?? 1,
};
}
const ADE_BANNER = String.raw`
_ ____ _____
/ \ | _ \| ____|
/ _ \ | | | | _|
/ ___ \| |_| | |___
/_/ \_\____/|_____|
`;
const TOP_LEVEL_HELP = `${ADE_BANNER}
Agent-focused command-line interface for ADE.
ADE CLI commands operate through the machine ADE runtime daemon by default.
If the daemon is not running, the CLI starts it, registers the selected
project, and routes project actions through that runtime.
$ ade help <command...> Display help for a command
$ ade auth status Check local ADE CLI readiness
$ ade code Open ADE Work chat in the terminal
$ ade desktop Launch the installed desktop app
$ ade runtime start | stop | status Manage the machine runtime daemon
$ ade serve Run the ADE runtime daemon in foreground
$ ade rpc --stdio Speak ADE JSON-RPC over stdin/stdout
$ ade init [path] Register a project with this machine runtime
$ ade projects list List projects registered on this machine
$ ade sync status | pin generate Manage machine sync and phone pairing
$ ade doctor Inspect project, socket, runtime, and tool availability
$ ade lanes list | show | create | child Work with lanes and lane stacks
$ ade git status | commit | push | stash Run ADE-aware git operations
$ ade operations status | wait Poll operation/test/chat/run/mission status
$ ade diff changes | file | patch Inspect lane diffs (including raw git patch text)
$ ade files tree | read | write | search Read and edit lane workspaces
$ ade missions launch | watch | graph Create, start, and inspect mission runs
$ ade prs list | create | path-to-merge Manage PRs, queues, and Path to Merge repair rounds
$ ade run defs | ps | start | logs Manage Run tab process definitions and runtime
$ ade shell start | write | resize | close Launch and control tracked shell sessions
$ ade terminal list | read | write | signal Control the active in-chat terminal
$ ade chat list | create | send | interrupt Work with ADE agent chats
$ ade agent spawn --lane <id> --prompt <text> Launch an agent session in ADE
$ ade cto state | chats Operate CTO state and Work chats
$ ade linear workflows | run | sync Operate Linear routing and sync workflows
$ ade automations list | create | run | runs Manage automation rules
$ ade coordinator <tool> Call coordinator runtime tools
$ ade tests list | run | stop | runs | logs Run configured test suites
$ ade proof status | list | screenshot | record Manage proof and computer-use artifacts
$ ade ios-sim devices | apps | launch | tap Control iOS Simulator apps, capture, and input
$ ade app-control launch | snapshot | click Inspect and drive Electron apps
$ ade macos-vm status | start | guide Run lane-tied macOS VMs for agent work
$ ade browser open | tabs | screenshot Use ADE's built-in browser pane
$ ade memory add | search | pin Use ADE memory
$ ade usage snapshot | refresh | budget Read provider quota usage and edit automation guardrails
$ ade settings action <method> Call project config actions
$ ade update status | check | install | dismiss Read auto-update state and drive install
$ ade actions list | run | status | wait Escape hatch for every ADE service action
$ ade mcp Expose ADE actions over stdio MCP
$ ade cursor cloud agents | runs | artifacts | repos | models | me
Drive Cursor Cloud agents via @cursor/sdk
Global options:
--project-root <path> ADE project root. Inside .ade/worktrees/<lane>, this resolves to the parent project.
--workspace-root <path> Lane/worktree to treat as the active workspace.
--headless Skip the runtime daemon and run an in-process ADE runtime.
--socket Require a live ADE socket; fail instead of falling back to headless.
--json Print machine-readable JSON. This is the default output mode.
--text Print a compact human-readable summary when a formatter exists.
--timeout-ms <ms> Per-request timeout. Long agent/PR workflows may need several minutes.
Common agent flows:
$ ade doctor --text
$ ade lanes list --text
$ ade lanes create --name fix-login --description "Repair login redirect"
$ ade git status --lane <lane> --text
$ ade git status --full --lane <lane> --text
$ ade git sync --lane <lane> --rebase --base main
$ ade git stage --lane <lane> src/index.ts
$ ade git commit --lane <lane> -m "Fix login redirect"
$ ade missions launch --prompt "Fix onboarding" --manual --text
$ ade prs create --lane <lane> --base main --draft
$ ade prs path-to-merge <pr-id-or-number-or-url> --model <model> --max-rounds 3 --no-auto-merge
$ ade proof record --seconds 20
$ ade ios-sim apps --text
$ ade ios-sim launch --target <id> --text
$ ade app-control launch --command "pnpm dev" --text
$ ade macos-vm start --lane <lane> --create --text
$ ade macos-vm guide --lane <lane> --text
$ ade --socket browser open http://localhost:5173 --new-tab --text
$ ade terminal read --chat-session <id> --text
Generic ADE action JSON contract:
Object-shaped call:
$ ade actions run git.push --input-json '{"laneId":"lane-1","setUpstream":true}'
$ ade actions run git.push --arg laneId=lane-1 --arg setUpstream=true
JSON value fields:
$ ade actions run pr.setLabels --arg prId=123 --arg-json 'labels=["ready","ship"]'
Multi-parameter service call:
$ ade actions run issue_inventory.savePipelineSettings --args-list-json '["pr-1",{"maxRounds":3}]'
Single scalar parameter:
$ ade actions run mission.get --scalar mission-1
$ ade actions list --text
$ ade actions list --domain pr --text
$ ade actions run <domain.action> --input-json '{"key":"value"}'
Start with: ade doctor --text
`;
const IOS_SIMULATOR_SUBCOMMAND_HELP: Record<string, string> = {
status: `${ADE_BANNER}
iOS Simulator: status
Shows macOS support, Xcode/idb/ffmpeg readiness, the active booted device,
and the drawer's active simulator session. Start here when a simulator action
fails or when an agent needs to know whether ADE owns a running session.
$ ade --socket ios-sim status --text
Flags:
--text Compact human-readable readiness summary.
--json Full JSON payload with tool install hints.
`,
devices: `${ADE_BANNER}
iOS Simulator: devices
Lists available iOS simulator devices. Aliases: list, ls.
$ ade --socket ios-sim devices --text
Flags:
--text Compact table.
--json Full device records.
`,
apps: `${ADE_BANNER}
iOS Simulator: apps
Lists launchable app targets from root-level .xcodeproj bundles,
apps/*/*.xcodeproj projects, DerivedData, and apps already installed on the
selected simulator. Aliases: targets, launchable, launchables.
$ ade --socket ios-sim apps --device <udid> --text
Flags:
--device, --udid <id> Simulator device to inspect.
--project-root <path> ADE project root to scan for iOS projects.
--text Compact table with target ids.
`,
launch: `${ADE_BANNER}
iOS Simulator: launch
Boots the simulator, resolves/builds/installs a target, launches the app, and
claims the ADE drawer session. Use --socket when the drawer and agents should
share one long-lived simulator service. Alias: open.
$ ade --socket ios-sim launch --target <id> --text
$ ade --socket ios-sim launch --bundle-id com.example.app --no-build --text
Flags:
--device, --udid <id> Simulator device.
--target, --target-id <id> Target id from "ios-sim apps".
--bundle-id, --bundle <id> Launch an installed app by bundle id.
--app-bundle, --app <path> Install/launch a built .app bundle.
--project, --xcodeproj <p> Xcode project path.
--scheme <name> Xcode scheme.
--project-root <path> ADE project root.
--lane, --lane-id <id> Lane to bind this simulator session to.
--chat-session <id> Owner chat session for the single-owner lock.
--no-build Skip xcodebuild.
--mode snapshot|live Inspector launch mode; default live.
--foreground Open and bring Simulator.app forward.
--arg KEY=VALUE Extra service args for advanced launch options.
`,
shutdown: `${ADE_BANNER}
iOS Simulator: shutdown
Stops streams, releases the drawer session, and tears down simulator helper processes.
Aliases: stop, teardown, end, end-session.
$ ade --socket ios-sim shutdown --text
$ ade --socket ios-sim shutdown --force --text
Flags:
--force, -f Release a session owned by another chat.
--device, --udid <id> Optional device context for cleanup.
`,
actions: `${ADE_BANNER}
iOS Simulator: actions
Lists every callable ios_simulator action exposed through ADE's generic action
bridge. Use this when a typed subcommand is missing a niche argument.
$ ade --socket ios-sim actions --text
$ ade actions run ios_simulator.getStatus --text
`,
screenshot: `${ADE_BANNER}
iOS Simulator: screenshot
Captures a one-shot PNG from the simulator via simctl. Alias: capture.
$ ade --socket ios-sim screenshot --device <udid> --text
Flags:
--device, --udid <id> Simulator device; defaults to the active session or booted device.
`,
snapshot: `${ADE_BANNER}
iOS Simulator: snapshot
Captures screenshot + ADEInspector/accessibility elements for the current
simulator screen. Use this before asking an agent to find the current screen
in SwiftUI code. Aliases: screen, elements.
$ ade --socket ios-sim snapshot --text
Flags:
--device, --udid <id> Simulator device.
--project-root <path> Project root for source matching.
--arg x=<n> --arg y=<n> Optional hit-test point in screenshot pixels.
`,
inspector: `${ADE_BANNER}
iOS Simulator: inspector
Reads the DEBUG ADEInspector snapshot published by the launched app. This is
lower-level than "snapshot" and does not include screenshot/accessibility fallback.
$ ade --socket ios-sim inspector --text
Flags:
--device, --udid <id> Simulator device.
`,
inspect: `${ADE_BANNER}
iOS Simulator: inspect
Hit-tests a point and returns the best matching context item without committing
it to the drawer composer. Aliases: hit-test, hover.
$ ade --socket ios-sim inspect --x 120 --y 420 --screenshot --text
Flags:
--x <n> --y <n> Required screenshot-pixel coordinates.
--device, --udid <id> Simulator device.
--project-root <path> Project root for Swift source matching.
--screenshot Include screenshot data in the context result.
`,
"preview-status": `${ADE_BANNER}
iOS Simulator: preview-status
Checks Xcode Preview Lab readiness: Xcode version, mcpbridge availability,
Xcode running state, selected project window, setup warnings, and docs URL.
Alias: preview-doctor.
$ ade --socket ios-sim preview-status --source apps/ios/ADE/Views/Home.swift --line 42 --text
Flags:
--project-root <path> ADE project root.
--source, --file <p> Swift file used to bias preview discovery.
--line <n> Source line used to bias preview discovery.
`,
previews: `${ADE_BANNER}
iOS Simulator: previews
Lists discoverable #Preview and PreviewProvider definitions, ranked around a
selected Swift file when supplied. Aliases: preview-list, list-previews.
$ ade --socket ios-sim previews --source apps/ios/ADE/Views/Home.swift --text
Flags:
--project-root <path> ADE project root.
--source, --file <p> Swift file to rank nearby previews.
--line <n> Optional source line.
`,
"preview-render": `${ADE_BANNER}
iOS Simulator: preview-render
Renders a SwiftUI preview through Xcode MCP and returns the snapshot path/data.
This is the final command agents should run after finding or adding a preview.
Aliases: render-preview, preview.
$ ade --socket ios-sim preview-render --source apps/ios/ADE/Views/Home.swift --index 0 --text
Flags:
--source, --file <p> Required Swift source file. Absolute, project-relative,
or Xcode-project-relative paths are accepted.
--index <n> Preview definition index in the file; default 0.
--tab, --tab-identifier <id> Xcode window tab from preview-status.
--timeout <sec> Render timeout, 5-240 seconds; default 120.
--project-root <path> ADE project root.
`,
"preview-open": `${ADE_BANNER}
iOS Simulator: preview-open
Opens apps/ios/ADE.xcodeproj in Xcode so Xcode MCP Preview Lab can connect.
Aliases: open-preview-workspace, open-xcode.
$ ade ios-sim preview-open --project-root <path> --text
Flags:
--project-root <path> ADE project root.
`,
"stream-start": `${ADE_BANNER}
iOS Simulator: stream-start
Starts a visual stream. auto resolves to iosurface-indigo first when full
Xcode supports ADE's private helpers, then Simulator.app window capture when
visible-window capture is allowed, then idb MJPEG, then simctl screenshot
polling. The H.264+ffmpeg idb stream is recovery-only after idb MJPEG fails.
Aliases:
start-stream, stream, window-start,
start-window, mirror-start, live-start, start-live, preview-start, start-preview.
$ ade --socket ios-sim window-start --fps 60 --text
$ ade --socket ios-sim live-start --fps 30 --text
$ ade --socket ios-sim preview-start --fps 8 --text
Flags:
--device, --udid <id> Simulator device.
--fps <n> Target fps.
--backend auto|iosurface-indigo|simulator-window-capture|idb-mjpeg|idb-h264-ffmpeg-mjpeg|simctl-screenshot-poll
--window, --mirror Force window capture.
--idb, --live Use auto backend resolution.
--simctl, --preview Force simctl screenshot polling.
`,
"stream-status": `${ADE_BANNER}
iOS Simulator: stream-status
Shows running backend, fallback/degradation reason, helper pid, fps, latency,
stream URL, frame count, input backend, and last error. Low idle fps is normal
on iosurface-indigo because frames are event-driven when the simulator is still.
$ ade --socket ios-sim stream-status --text
`,
"stream-stop": `${ADE_BANNER}
iOS Simulator: stream-stop
Stops the visual stream without necessarily releasing the simulator session.
Aliases: stop-stream, preview-stop, stop-preview, live-stop, stop-live.
$ ade --socket ios-sim stream-stop --text
`,
select: `${ADE_BANNER}
iOS Simulator: select
Hit-tests a point, emits a drawer selection event, and attaches the resulting
iOS context to the active chat composer. Use --socket so the drawer receives it.
$ ade --socket ios-sim select --x 120 --y 420 --text
Flags:
--x <n> --y <n> Required screenshot-pixel coordinates.
--device, --udid <id> Simulator device.
--project-root <path> Project root for Swift source matching.
`,
tap: `${ADE_BANNER}
iOS Simulator: tap
Sends a tap through the active input backend, preferring Indigo with idb fallback.
$ ade --socket ios-sim tap --x 120 --y 420 --text
$ ade --socket ios-sim tap 120 420 --text
Flags:
--x <n> --y <n> Required point coordinates.
--device, --udid <id> Simulator device.
--project-root <path> Project root.
`,
drag: `${ADE_BANNER}
iOS Simulator: drag / swipe
Sends a swipe through the active input backend. "swipe" is an alias of drag.
$ ade --socket ios-sim drag --start-x 120 --start-y 700 --end-x 120 --end-y 250 --text
$ ade --socket ios-sim swipe 120 700 120 250 --duration-ms 250 --text
Flags:
--start-x <n> --start-y <n> Required start coordinates.
--end-x <n> --end-y <n> Required end coordinates.
--duration-ms <n> Swipe duration in milliseconds.
--device, --udid <id> Simulator device.
--project-root <path> Project root.
`,
type: `${ADE_BANNER}
iOS Simulator: type
Types text through idb into the active launched app. Alias: text.
$ ade --socket ios-sim type "hello" --text
$ ade --socket ios-sim type --value "hello" --text
Flags:
--value, --message <v> Text to type. --text <value> is also accepted for
compatibility, but --text by itself controls ADE's
human-readable output mode.
--device, --udid <id> Simulator device.
--project-root <path> Project root.
`,
};
const IOS_SIMULATOR_HELP_ALIASES: Record<string, string> = {
list: "devices",
ls: "devices",
targets: "apps",
launchable: "apps",
launchables: "apps",
open: "launch",
stop: "shutdown",
teardown: "shutdown",
end: "shutdown",
"end-session": "shutdown",
capture: "screenshot",
screen: "snapshot",
elements: "snapshot",
"hit-test": "inspect",
hover: "inspect",
"preview-doctor": "preview-status",
"preview-list": "previews",
"list-previews": "previews",
"render-preview": "preview-render",
preview: "preview-render",
"open-preview-workspace": "preview-open",
"open-xcode": "preview-open",
"start-stream": "stream-start",
stream: "stream-start",
"window-start": "stream-start",
"start-window": "stream-start",
"mirror-start": "stream-start",
"start-mirror": "stream-start",
"live-start": "stream-start",
"start-live": "stream-start",
"preview-start": "stream-start",
"start-preview": "stream-start",
"stop-stream": "stream-stop",
"preview-stop": "stream-stop",
"stop-preview": "stream-stop",
"live-stop": "stream-stop",
"stop-live": "stream-stop",
swipe: "drag",
text: "type",
};
const HELP_BY_COMMAND: Record<string, string> = {
desktop: `${ADE_BANNER}
ADE Desktop
Launch the installed ADE desktop app. The desktop app attaches to the normal
machine runtime and starts it if needed.
$ ade desktop
$ ade desktop open
Flags:
--app-name <name> macOS app name to open. Defaults to ADE, ADE Beta,
or ADE Alpha based on the installed CLI wrapper.
`,
runtime: `${ADE_BANNER}
ADE Runtime
Manage the normal machine ADE runtime daemon used by desktop, ade code, and
socket-backed CLI commands.
$ ade runtime status --text
$ ade runtime start
$ ade runtime stop
Notes:
"start" launches the daemon in the background if it is missing.
"stop" shuts down the daemon on the selected socket.
Use "ade serve" when you want to run the runtime in the foreground.
`,
serve: `${ADE_BANNER}
ADE Runtime Daemon
Runs the machine-scoped ADE runtime in the foreground. The daemon listens on
a local socket and can lazily serve any project registered with "ade init".
$ ade serve
$ ade serve --socket ~/.ade/sock/ade.sock
$ ade serve --port 8787
Flags:
--socket <path> Unix socket or Windows named pipe to listen on.
--port <n> Also listen for local TCP JSON-RPC on 127.0.0.1:n.
--no-sync Disable machine sync discovery for this daemon run.
--install-service Register the per-user login service and exit.
--uninstall-service Remove the per-user login service and exit.
--service-status Print per-user login service status and exit.
`,
rpc: `${ADE_BANNER}
ADE JSON-RPC
Attaches to the machine runtime daemon and speaks ADE JSON-RPC over stdio.
If the daemon is not running, ADE starts it before accepting requests. This
mode is used by SSH transports.
$ ade rpc --stdio
`,
init: `${ADE_BANNER}
ADE Project Init
Registers a project with this machine runtime and creates its .ade directory
if needed.
$ ade init
$ ade init /path/to/project
`,
projects: `${ADE_BANNER}
ADE projects
Manage the machine-scoped ADE project registry used by the runtime daemon.
$ ade projects list --text
$ ade projects add /path/to/project
$ ade projects remove <project-id>
$ ade projects touch <project-id>
`,
code: `${ADE_BANNER}
ADE Code
Launch the terminal-native ADE Work chat. It uses the same project lanes,
chat sessions, transcript state, and slash commands as desktop ADE, but it
does not require the desktop app to be running.
$ ade code Start the TUI for the current project
$ ade code --print-state Smoke-test attach/embed state
$ ade code --embedded Force the embedded runtime fallback
$ ade code --require-socket Fail instead of embedding when no socket exists
$ ade code --socket /tmp/ade.sock Attach to a specific runtime socket
$ ade --project-root <path> code Launch against a specific ADE project
Keys:
ctrl-o Open or focus lanes and chats
ctrl-p Open or focus details
shift-tab Cycle pane focus
esc Return or cancel the active pane
? Help when it is the first prompt character
/ Command palette
`,
lanes: `${ADE_BANNER}
Lanes
Lanes are ADE-managed worktrees and branches. Most commands accept either
--lane <lane-id> or a positional lane id.
$ ade lanes list --text Show lane stack graph and branch names
$ ade lanes show <lane> --text Inspect one lane status
$ ade lanes create --name <name> Create a lane from the current project context
$ ade lanes create --linear-issue-json '{...}' Create a lane linked to a Linear issue
$ ade lanes create --branch-name <branch> Override the auto-generated branch name
$ ade lanes child --lane <parent> --name <name> Create a child lane under a parent
$ ade lanes import --branch <branch> Register an existing branch/worktree
$ ade lanes archive <lane> Archive a lane in ADE
$ ade lanes unarchive <lane> Restore an archived lane
$ ade lanes attach --path <worktree> --name <n> Attach an external worktree
$ ade lanes actions --text List callable lane service methods
`,
git: `${ADE_BANNER}
Git
Git commands run in the lane worktree and record ADE operations so the app can
refresh lane state. Use --lane for anything other than the active workspace.
$ ade git status --lane <lane> --text Show ADE-aware sync status
$ ade git status --full --lane <lane> --text Show full lane status, diff, and conflict state
$ ade git fetch --lane <lane> Fetch remote refs
$ ade git pull --lane <lane> Pull with ADE's ff-only lane operation
$ ade git sync --lane <lane> --rebase --base main
Sync the lane with its base branch
$ ade git stage --lane <lane> src/file.ts Stage one file
$ ade git stage-all --lane <lane> Stage all current changes
$ ade git unstage --lane <lane> src/file.ts Unstage one file
$ ade git commit --lane <lane> [-m <message>] Commit, adding Refs <issue-id> on linked Linear lanes
$ ade git push --lane <lane> --set-upstream Push through ADE
$ ade git push --lane <lane> --force-with-lease Force-push through ADE with lease
$ ade git branches --lane <lane> --text List branches with last-commit metadata
$ ade git user-identity --lane <lane> --text Read lane checkout's git user.name/email
$ ade git stash push|list|apply|pop Use ADE lane stash actions
$ ade git rebase --lane <lane> --ai Rebase with ADE conflict support
$ ade git rebase continue --lane <lane> Continue an in-progress rebase
$ ade git conflict show --lane <lane> --text Inspect merge/rebase conflict state
$ ade git conflict resolve --kind rebase Continue after manual conflict resolution
$ ade diff changes --lane <lane> --text Inspect changed files
`,
operations: `${ADE_BANNER}
Operations
Poll status for long-running ADE operations that returned an operation,
test run, chat session, run graph, mission, or PR id.
$ ade operations status --operation <id> --text
$ ade operations wait --operation <id> --wait-ms 30000 --text
$ ade actions wait --test-run <id> --wait-ms 30000 --text
Generic operation logs are not persisted by the operation table. Use
"ade tests logs", "ade run logs", or terminal/app-control log commands for
surfaces that own logs.
`,
diff: `${ADE_BANNER}
Diffs
$ ade diff changes --lane <lane> --text Summarize staged/unstaged file changes
$ ade diff file --lane <lane> <path> --text Show one file diff (side-by-side text)
$ ade diff patch --lane <lane> <path> --text Raw unified diff / patch for one file
$ ade diff file --mode staged <path> Inspect staged diff for one file
$ ade diff actions --text List diff service actions
`,
prs: `${ADE_BANNER}
Pull requests
PR identifiers may be ADE PR ids, GitHub PR numbers, #numbers, or full PR URLs.
Creating or linking a PR persists the lane mapping in ADE so the PR tab tracks it.
$ ade prs list --text List PRs known to ADE
$ ade prs list-open --text List every open GitHub PR in the repo, keyed by head branch
$ ade prs create --lane <lane> --base main Open and map a GitHub PR from a lane
$ ade prs create --lane <lane> --close-linear-issue-on-merge
$ ade prs link --lane <lane> --url <pr-url> Map an existing GitHub PR to a lane
$ ade prs checks <pr> --text Show check status
$ ade prs comments <pr> --text Show unresolved review work
$ ade prs inventory <pr> Refresh ADE issue inventory
$ ade prs path-to-merge <pr> --model <model> --max-rounds 3 --no-auto-merge
$ ade prs path-to-merge <pr> --model <model> --conflict-strategy auto --force-finalize conditional
$ ade prs path-to-merge <pr> --model <model> --no-early-merge-on-green
$ ade prs pipeline <pr> save --conflict-strategy rebase --early-merge-on-green
$ ade prs resolve-thread <pr> --thread <id> Resolve a review thread
$ ade prs labels set <pr> ready-to-merge Replace labels