Skip to content

Commit ec4a3ef

Browse files
t3dotggclaude
andcommitted
feat(desktop): Add to PATH puts the t3 command on PATH in one click
When the desktop app's t3 link is off PATH (most macOS accounts), the welcome setup and Settings showed a long command to paste. They now show an Add to PATH button. The app appends one marked line to the shell's startup file (~/.zshrc, ~/.bashrc on Linux, or fish's config.fish), only once, and then reports it as added. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 1b43303 commit ec4a3ef

11 files changed

Lines changed: 161 additions & 70 deletions

File tree

‎apps/desktop/src/app/DesktopCliCommand.test.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,10 +132,19 @@ it.layer(NodeServices.layer)("DesktopCliCommand", (it) => {
132132
const installed = yield* command.install;
133133
expect(installed.installedPath).toBe(link);
134134
expect(installed.launcherPath).toBe(path.join(home, ".t3", "bin", "t3"));
135-
expect(installed.pathCommand).toContain("$HOME/.local/bin");
135+
expect(installed.pathSetup).toEqual({ file: "~/.zshrc", added: false });
136136
expect(yield* fs.readLink(link)).toBe(path.join(home, ".t3", "bin", "t3"));
137137
expect((yield* command.install).installedPath).toBe(link);
138138

139+
// Add to PATH appends one line, once, and keeps a final line with no newline intact.
140+
const zshrc = path.join(home, ".zshrc");
141+
yield* fs.writeFileString(zshrc, "# mine");
142+
yield* command.addToPath;
143+
expect((yield* command.addToPath).pathSetup).toEqual({ file: "~/.zshrc", added: true });
144+
expect(yield* fs.readFileString(zshrc)).toBe(
145+
'# mine\n# Added by T3 Code\nexport PATH="$HOME/.local/bin:$PATH"\n',
146+
);
147+
139148
expect((yield* command.uninstall).installedPath).toBeNull();
140149
expect(yield* fs.exists(link)).toBe(false);
141150
expect(yield* fs.exists(path.join(home, ".t3", "bin", "t3"))).toBe(true);

‎apps/desktop/src/app/DesktopCliCommand.ts‎

Lines changed: 39 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import * as Stream from "effect/Stream";
99
import * as ChildProcess from "effect/process/ChildProcess";
1010
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
1111

12-
import { pathSetupCommand } from "@t3tools/shared/shell";
12+
import { pathSetup } from "@t3tools/shared/shell";
1313

1414
import * as DesktopCliShim from "./DesktopCliShim.ts";
1515
import * as DesktopEnvironment from "./DesktopEnvironment.ts";
@@ -63,6 +63,8 @@ export class DesktopCliCommand extends Context.Service<
6363
readonly state: Effect.Effect<DesktopCliCommandState>;
6464
readonly install: Effect.Effect<DesktopCliCommandState, DesktopCliCommandError>;
6565
readonly uninstall: Effect.Effect<DesktopCliCommandState, DesktopCliCommandError>;
66+
/** Adds the installed command's folder to PATH in the user's shell startup file. */
67+
readonly addToPath: Effect.Effect<DesktopCliCommandState, DesktopCliCommandError>;
6668
/** Installs the command on an app's first launch; removing it in Settings sticks. */
6769
readonly installOnFirstLaunch: Effect.Effect<void>;
6870
}
@@ -159,6 +161,21 @@ export const make = Effect.gen(function* () {
159161
return Option.none<string>();
160162
});
161163

164+
const startupLine = (installedPath: string) => {
165+
const setup = pathSetup({
166+
directory: path.dirname(installedPath),
167+
home: environment.homeDirectory,
168+
shell: process.env.SHELL,
169+
platform: environment.platform,
170+
});
171+
return setup && { ...setup, path: path.join(environment.homeDirectory, setup.file.slice(2)) };
172+
};
173+
const hasLine = (setup: { readonly path: string; readonly line: string }) =>
174+
fs.readFileString(setup.path).pipe(
175+
Effect.map((content) => content.split("\n").some((line) => line.trim() === setup.line)),
176+
Effect.orElseSucceed(() => false),
177+
);
178+
162179
const state: DesktopCliCommand["Service"]["state"] = Effect.gen(function* () {
163180
if (!environment.isPackaged) {
164181
return { supported: false, installedPath: null, onPath: false, launcherPath: null } as const;
@@ -172,21 +189,16 @@ export const make = Effect.gen(function* () {
172189
}
173190
const first = yield* firstOnPath;
174191
const onPath = windows || (Option.isSome(first) && (yield* isOurLink(first.value)));
175-
const pathCommand = onPath
176-
? undefined
177-
: pathSetupCommand({
178-
directory: path.dirname(installed.value),
179-
home: environment.homeDirectory,
180-
shell: process.env.SHELL,
181-
platform: environment.platform,
182-
});
192+
const setup = onPath ? undefined : startupLine(installed.value);
183193
return {
184194
supported: true,
185195
installedPath: installed.value,
186196
onPath,
187197
launcherPath,
188198
...shadow,
189-
...(pathCommand === undefined ? {} : { pathCommand }),
199+
...(setup === undefined
200+
? {}
201+
: { pathSetup: { file: setup.file, added: yield* hasLine(setup) } }),
190202
};
191203
}).pipe(
192204
Effect.orElseSucceed(() => ({
@@ -286,6 +298,22 @@ export const make = Effect.gen(function* () {
286298
return yield* state;
287299
}).pipe(Effect.withSpan("desktop.cliCommand.uninstall"));
288300

301+
const addToPath: DesktopCliCommand["Service"]["addToPath"] = Effect.gen(function* () {
302+
const installed = yield* installedAt;
303+
if (Option.isNone(installed)) return yield* fail("Install the t3 command first.");
304+
const setup = startupLine(installed.value);
305+
if (setup === undefined) return yield* fail("T3 Code cannot add t3 to this shell's PATH.");
306+
if (!(yield* hasLine(setup))) {
307+
yield* fs.makeDirectory(path.dirname(setup.path), { recursive: true }).pipe(
308+
Effect.andThen(
309+
fs.writeFileString(setup.path, `\n# Added by T3 Code\n${setup.line}\n`, { flag: "a" }),
310+
),
311+
Effect.mapError(() => fail(`Could not add t3 to ${setup.file}.`)),
312+
);
313+
}
314+
return yield* state;
315+
}).pipe(Effect.withSpan("desktop.cliCommand.addToPath"));
316+
289317
const installOnFirstLaunch: DesktopCliCommand["Service"]["installOnFirstLaunch"] = Effect.gen(
290318
function* () {
291319
if (!environment.isPackaged || (yield* exists(firstLaunchMarker))) return;
@@ -304,7 +332,7 @@ export const make = Effect.gen(function* () {
304332
Effect.withSpan("desktop.cliCommand.installOnFirstLaunch"),
305333
);
306334

307-
return DesktopCliCommand.of({ state, install, uninstall, installOnFirstLaunch });
335+
return DesktopCliCommand.of({ state, install, uninstall, addToPath, installOnFirstLaunch });
308336
});
309337

310338
export const layer = Layer.effect(DesktopCliCommand, make);

‎apps/desktop/src/ipc/DesktopIpcHandlers.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ import {
7777
getCliCommandState,
7878
installCliCommand,
7979
uninstallCliCommand,
80+
addCliCommandToPath,
8081
} from "./methods/cliCommand.ts";
8182

8283
export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers")(function* () {
@@ -156,6 +157,7 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
156157
yield* ipc.handle(getCliCommandState);
157158
yield* ipc.handle(installCliCommand);
158159
yield* ipc.handle(uninstallCliCommand);
160+
yield* ipc.handle(addCliCommandToPath);
159161
for (const previewMethod of PreviewIpc.methods) {
160162
// Explicit types preserve the error/service union of these heterogeneous preview methods.
161163
yield* ipc.handle<

‎apps/desktop/src/ipc/channels.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ export const UPDATE_CHECK_CHANNEL = "desktop:update-check";
2929
export const CLI_COMMAND_GET_STATE_CHANNEL = "desktop:cli-command-get-state";
3030
export const CLI_COMMAND_INSTALL_CHANNEL = "desktop:cli-command-install";
3131
export const CLI_COMMAND_UNINSTALL_CHANNEL = "desktop:cli-command-uninstall";
32+
export const CLI_COMMAND_ADD_TO_PATH_CHANNEL = "desktop:cli-command-add-to-path";
3233
export const GET_APP_BRANDING_CHANNEL = "desktop:get-app-branding";
3334
export const GET_RELAY_TELEMETRY_ENABLED_CHANNEL = "desktop:get-relay-telemetry-enabled";
3435
export const GET_SYSTEM_LOCALE_CHANNEL = "desktop:get-system-locale";

‎apps/desktop/src/ipc/methods/cliCommand.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,12 @@ export const uninstallCliCommand = makeIpcMethod({
3232
return yield* (yield* DesktopCliCommand.DesktopCliCommand).uninstall;
3333
}),
3434
});
35+
36+
export const addCliCommandToPath = makeIpcMethod({
37+
channel: IpcChannels.CLI_COMMAND_ADD_TO_PATH_CHANNEL,
38+
payload: Schema.Void,
39+
result: DesktopCliCommandStateSchema,
40+
handler: Effect.fn("desktop.ipc.cliCommand.addToPath")(function* () {
41+
return yield* (yield* DesktopCliCommand.DesktopCliCommand).addToPath;
42+
}),
43+
});

‎apps/desktop/src/preload.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -270,6 +270,7 @@ contextBridge.exposeInMainWorld("desktopBridge", {
270270
getState: () => ipcRenderer.invoke(IpcChannels.CLI_COMMAND_GET_STATE_CHANNEL),
271271
install: () => ipcRenderer.invoke(IpcChannels.CLI_COMMAND_INSTALL_CHANNEL),
272272
uninstall: () => ipcRenderer.invoke(IpcChannels.CLI_COMMAND_UNINSTALL_CHANNEL),
273+
addToPath: () => ipcRenderer.invoke(IpcChannels.CLI_COMMAND_ADD_TO_PATH_CHANNEL),
273274
},
274275
onUpdateState: (listener) => {
275276
const wrappedListener = (_event: Electron.IpcRendererEvent, state: unknown) => {

‎apps/web/src/components/onboarding/WelcomeWizard.tsx‎

Lines changed: 21 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -72,16 +72,12 @@ import {
7272
useEnvironmentsWithScope,
7373
} from "../../state/session";
7474
import { terminalEnvironment } from "../../state/terminal";
75-
import {
76-
desktopCliCommandStateAtom,
77-
getDesktopCliCommandBridge,
78-
} from "../../state/desktopCliCommand";
79-
import { useEnvironmentQuery } from "../../state/query";
8075
import { useAtomCommand } from "../../state/use-atom-command";
8176
import { connectPairing } from "../../connection/onboarding";
8277
import { getProviderSummary } from "../settings/providerStatus";
8378
import { providerClients } from "../settings/providerDriverMeta";
8479
import { ChatGptWelcomeCoordinator } from "../settings/ChatGptWelcomeCoordinator";
80+
import { useDesktopCliCommand } from "../settings/CliCommandSettingsRow";
8581
import { AddManagedCodexAccountDialog, CodexSetupSection } from "../settings/CodexSetupSection";
8682
import { readCodexSetupMode } from "../settings/CodexSetupSection.logic";
8783
import { buildProviderInstanceUpdatePatch } from "../settings/SettingsPanels.logic";
@@ -92,7 +88,6 @@ import { ProviderInstanceIcon } from "../chat/ProviderInstanceIcon";
9288
import { T3Wordmark } from "../T3Wordmark";
9389
import { Alert, AlertDescription } from "../ui/alert";
9490
import { Button } from "../ui/button";
95-
import { CommandBlock } from "../CommandBlock";
9691
import { InstallT3Commands } from "../InstallT3Commands";
9792
import { Checkbox } from "../ui/checkbox";
9893
import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "../ui/collapsible";
@@ -1763,18 +1758,30 @@ function ImportRowMeta({
17631758
);
17641759
}
17651760

1766-
/** The desktop app links `t3` on first launch; this shows how to put its folder on PATH. */
1761+
/** The desktop app links `t3` on first launch; this puts its folder on PATH when it is not. */
17671762
function CliPathSetup() {
1768-
const bridge = getDesktopCliCommandBridge();
1769-
const pathCommand = useEnvironmentQuery(bridge ? desktopCliCommandStateAtom : null).data
1770-
?.pathCommand;
1771-
if (!pathCommand) return null;
1763+
const { state, busy, run } = useDesktopCliCommand();
1764+
const setup = state?.pathSetup;
1765+
if (!setup) return null;
17721766
return (
1773-
<div className="mt-5">
1767+
<div className="mt-5 flex items-center justify-between gap-3">
17741768
<p className="text-sm text-muted-foreground">
1775-
Run this once to use <code className="font-mono">t3</code> in new terminals.
1769+
{setup.added ? (
1770+
<>
1771+
Added to {setup.file}. Open a new terminal to use <code className="font-mono">t3</code>.
1772+
</>
1773+
) : (
1774+
<>
1775+
Use <code className="font-mono">t3</code> from any terminal. Adds one line to{" "}
1776+
{setup.file}.
1777+
</>
1778+
)}
17761779
</p>
1777-
<CommandBlock command={pathCommand} className="mt-2" />
1780+
{setup.added ? null : (
1781+
<Button size="sm" variant="outline" disabled={busy} onClick={() => run("addToPath")}>
1782+
Add to PATH
1783+
</Button>
1784+
)}
17781785
</div>
17791786
);
17801787
}

‎apps/web/src/components/settings/CliCommandSettingsRow.tsx‎

Lines changed: 45 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,19 @@ import { stackedThreadToast, toastManager } from "../ui/toast";
1111
import { SettingsRow } from "./settingsLayout";
1212
import { searchableSetting } from "./settingsSearch";
1313

14-
export function CliCommandSettingsRow() {
14+
const FAILURE_TITLES = {
15+
install: "Could not install t3",
16+
uninstall: "Could not remove t3",
17+
addToPath: "Could not add t3 to PATH",
18+
} as const;
19+
20+
/** The desktop `t3` command's state, and its actions with a toast on failure. */
21+
export function useDesktopCliCommand() {
1522
const bridge = getDesktopCliCommandBridge();
1623
const query = useEnvironmentQuery(bridge ? desktopCliCommandStateAtom : null);
17-
const state = query.data;
1824
const [pending, setPending] = useState(false);
1925

20-
const change = (action: "install" | "uninstall") => {
26+
const run = (action: keyof typeof FAILURE_TITLES) => {
2127
if (!bridge || pending) return;
2228
setPending(true);
2329
void bridge[action]()
@@ -26,44 +32,56 @@ export function CliCommandSettingsRow() {
2632
toastManager.add(
2733
stackedThreadToast({
2834
type: "error",
29-
title: action === "install" ? "Could not install t3" : "Could not remove t3",
35+
title: FAILURE_TITLES[action],
3036
description: error instanceof Error ? error.message : "Something went wrong.",
3137
}),
3238
);
3339
})
3440
.finally(() => setPending(false));
3541
};
3642

37-
if (!bridge || !state?.supported) return null;
43+
return {
44+
state: bridge ? query.data : undefined,
45+
busy: pending || query.isPending,
46+
run,
47+
};
48+
}
49+
50+
export function CliCommandSettingsRow() {
51+
const { state, busy, run } = useDesktopCliCommand();
52+
53+
if (!state?.supported) return null;
3854
const installed = state.installedPath !== null;
39-
const description = state.shadowedBy ? (
40-
`Another t3 at ${state.shadowedBy} runs first in a new terminal. Remove it to use T3 Code's.`
41-
) : !installed ? (
42-
"Run T3 Code's CLI as `t3` from any terminal."
43-
) : state.onPath ? (
44-
`Installed at ${state.installedPath}. Open a new terminal to use it.`
45-
) : state.pathCommand ? (
46-
<>
47-
Installed at {state.installedPath}, which is not on your PATH yet. Run{" "}
48-
<code className="select-all font-mono">{state.pathCommand}</code>, then open a new terminal.
49-
</>
50-
) : (
51-
`Installed at ${state.installedPath}, which is not on your PATH yet. Add its folder to your PATH to run \`t3\`.`
52-
);
55+
const description = state.shadowedBy
56+
? `Another t3 at ${state.shadowedBy} runs first in a new terminal. Remove it to use T3 Code's.`
57+
: !installed
58+
? "Run T3 Code's CLI as `t3` from any terminal."
59+
: state.onPath
60+
? `Installed at ${state.installedPath}. Open a new terminal to use it.`
61+
: state.pathSetup?.added
62+
? `Installed at ${state.installedPath} and added to PATH in ${state.pathSetup.file}. Open a new terminal to use it.`
63+
: `Installed at ${state.installedPath}, which is not on your PATH yet.${state.pathSetup ? "" : " Add its folder to your PATH to run `t3`."}`;
5364

5465
return (
5566
<SettingsRow
5667
{...searchableSetting("cli-command")}
5768
description={description}
5869
control={
59-
<Button
60-
size="sm"
61-
variant="outline"
62-
disabled={pending || query.isPending}
63-
onClick={() => change(installed ? "uninstall" : "install")}
64-
>
65-
{installed ? "Remove" : "Install"}
66-
</Button>
70+
<div className="flex gap-2">
71+
{state.pathSetup && !state.pathSetup.added ? (
72+
<Button size="sm" variant="outline" disabled={busy} onClick={() => run("addToPath")}>
73+
Add to PATH
74+
</Button>
75+
) : null}
76+
<Button
77+
size="sm"
78+
variant="outline"
79+
disabled={busy}
80+
onClick={() => run(installed ? "uninstall" : "install")}
81+
>
82+
{installed ? "Remove" : "Install"}
83+
</Button>
84+
</div>
6785
}
6886
/>
6987
);

‎docs/user/install.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -89,11 +89,11 @@ update fails. Download the new `.deb` and install it the same way.
8989
The desktop app includes the `t3` command-line tool and installs it on first
9090
launch. On macOS and Linux it adds a `t3` link in `~/.local/bin` (or `~/bin`);
9191
on Windows it adds the app's command folder to your `PATH`. Open a new terminal
92-
afterwards. If the folder is not on your `PATH`, the welcome setup and
93-
**Settings → About** show the command that adds it. On a new Ubuntu account, `~/.local/bin` joins your `PATH`
94-
the next time you log in, so logging out and back in also works. **Remove** next
95-
to **t3 command** takes it off, and the app does not add it again; **Install**
96-
puts it back. If you already have another `t3`, it stays as it is.
92+
afterwards. If the folder is not on your `PATH`, **Add to PATH** in the welcome
93+
setup or **Settings → About** adds one line to your shell's startup file. On a
94+
new Ubuntu account, `~/.local/bin` joins your `PATH` the next time you log in, so
95+
logging out and back in also works. **Remove** next to **t3 command** takes it
96+
off, and the app does not add it again; **Install** puts it back. If you already have another `t3`, it stays as it is.
9797

9898
### Windows Subsystem for Linux
9999

‎packages/contracts/src/ipc.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -321,8 +321,8 @@ export const DesktopCliCommandStateSchema = Schema.Struct({
321321
installedPath: Schema.NullOr(Schema.String),
322322
onPath: Schema.Boolean,
323323
shadowedBy: Schema.optionalKey(Schema.String),
324-
/** A command to paste that puts an installed `t3` that is off PATH onto it. */
325-
pathCommand: Schema.optionalKey(Schema.String),
324+
/** For an installed `t3` that is off PATH: the shell startup file that adds it, and whether it has. */
325+
pathSetup: Schema.optionalKey(Schema.Struct({ file: Schema.String, added: Schema.Boolean })),
326326
/** The app's bundled `t3` launcher, which runs without Node or a PATH entry. */
327327
launcherPath: Schema.NullOr(Schema.String),
328328
});
@@ -1107,6 +1107,7 @@ export interface DesktopBridge {
11071107
getState: () => Promise<DesktopCliCommandState>;
11081108
install: () => Promise<DesktopCliCommandState>;
11091109
uninstall: () => Promise<DesktopCliCommandState>;
1110+
addToPath: () => Promise<DesktopCliCommandState>;
11101111
};
11111112
webLinks: {
11121113
setReady: (ready: boolean) => Promise<void>;

0 commit comments

Comments
 (0)