Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 51 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,8 +189,8 @@ machine you are signing in, so it works over SSH, in containers and on servers
without a browser.

`npx toolstile auth login` runs only the sign-in, the same way. Setup also signs
in again when the saved sign-in has expired, or when `--server` names a
different Toolstile address than the one this machine is signed in to.
in again when the saved sign-in has expired, or when it targets a server this
machine is not signed in to yet.

`mcp setup` lists the agents it finds (Claude Code, Claude Desktop, Cursor,
Codex, VS Code, Windsurf, Devin Desktop, Gemini CLI, Cline, Grok Build, OpenCode,
Expand Down Expand Up @@ -223,17 +223,61 @@ folder: `$TOOLSTILE_CONFIG_DIR` when set, otherwise `%APPDATA%\toolstile` on
Windows and `$XDG_CONFIG_HOME/toolstile` (default `~/.config/toolstile`)
elsewhere.

`npx toolstile auth logout` ends the CLI's sign-in. Agents you enabled keep
working until you turn them off with `mcp setup` or delete the device in the
dashboard.
`npx toolstile auth logout` ends the CLI's sign-in to the current server. Agents
you enabled keep working until you turn them off with `mcp setup` or delete the
device in the dashboard.

### Cloud, self-hosted or local

The `auth` and `mcp` commands work with three kinds of Toolstile server:

| Server | How to pick it |
| --- | --- |
| Toolstile Cloud, `https://app.toolstile.com` | The default |
| A self-hosted server | `--server https://toolstile.example.com` |
| The self-hosted server on this machine | `--local` |

`--local` uses the `origin` from the server's `instance.json`, in
`$TOOLSTILE_DATA_DIR` (default `~/.local/share/toolstile`), or
`http://127.0.0.1:4310` when there is none. The CLI reads only that field; the
file's keys are never printed or copied. Plain `http://` works only for
`localhost`, `127.0.0.0/8` and `[::1]`; every other server must use `https://`.

The CLI keeps one sign-in per server. The last server you signed in to is the
current one. Each command uses `--server` or `--local` when given, then the
`TOOLSTILE_SERVER` environment variable (`TOOLSTILE_URL` also works), then the
current server.

```sh
npx toolstile auth login --local # sign in to the server on this machine
npx toolstile mcp setup --enable codex # set up Codex there, the current server now
npx toolstile auth status # every saved sign-in; * marks the current one
npx toolstile whoami --server https://app.toolstile.com
npx toolstile auth logout --all # sign out everywhere
```

A self-hosted server has no workspaces, so setup does not ask for one and
`--workspace` is refused. Each agent uses one server, and agents on one machine
can use different servers: setup on one server leaves agents that use another
alone. Turning on an agent that uses another server moves it, so setup asks
first; without a terminal, add `--switch`. Its access on the old server is
removed when this machine is still signed in there.

An agent's token is only ever sent to the server that issued it. `mcp proxy`
ignores `--server`, `--local` and `TOOLSTILE_SERVER`, and never follows a
redirect.

| Option | Command | Meaning |
| --- | --- | --- |
| `--server <url>` | `auth login`, `mcp setup` | Toolstile address (default `https://app.toolstile.com`, or `TOOLSTILE_URL`) |
| `--server <url>` | `auth login`, `auth logout`, `whoami`, `mcp setup` | Use this server (default: `TOOLSTILE_SERVER`, else the current one) |
| `--local` | `auth login`, `auth logout`, `whoami`, `mcp setup` | Use the self-hosted server on this machine |
| `--all` | `auth logout` | Sign out of every server |
| `--json` | `auth status`, `whoami` | Print JSON |
| `--no-browser` | `auth login`, `mcp setup` | Do not try to open a browser on this machine |
| `--enable <agents>` | `mcp setup` | Turn these on without prompting (comma-separated) |
| `--disable <agents>` | `mcp setup` | Turn these off without prompting |
| `--workspace <slug>` | `mcp setup` | Workspace the agents use (default: the last one, or personal) |
| `--switch` | `mcp setup` | Move agents that use another server to this one without asking |
| `--workspace <slug>` | `mcp setup` | Toolstile Cloud workspace the agents use (default: the last one, or personal) |
| `--device-name <name>` | `mcp setup` | Name for this machine in the dashboard (default: its hostname) |

## Use it from code
Expand Down
26 changes: 19 additions & 7 deletions src/api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,9 @@ export interface Account {
email: string;
name: string;
expiresAt: string;
/** Which kind of server this is. Servers from before this field are Toolstile Cloud. */
edition?: "cloud" | "self-hosted";
/** Toolstile Cloud workspaces; a self-hosted server returns none. */
workspaces: Workspace[];
/** The device named when this sign-in was approved. */
device?: { id: string; label: string } | null;
Expand Down Expand Up @@ -75,7 +78,16 @@ async function request<T>(fetcher: Fetch, url: string, init: RequestInit = {}):
});
}

/** The Toolstile endpoints the CLI uses. Session calls carry the device-flow session token. */
/** Query parameters, leaving out the ones that are not set. */
function query(params: Record<string, string | undefined>): string {
const defined = Object.entries(params).filter((entry): entry is [string, string] => entry[1] !== undefined);
return defined.length ? `?${new URLSearchParams(defined)}` : "";
}

/**
* The Toolstile endpoints the CLI uses. Session calls carry the device-flow session token.
* `workspaceId` is for Toolstile Cloud; requests to a self-hosted server leave it out.
*/
export function createApi(server: string, fetcher: Fetch = fetch) {
const base = server.replace(/\/+$/, "");
const session = (token: string, init: RequestInit = {}): RequestInit => ({
Expand All @@ -99,28 +111,28 @@ export function createApi(server: string, fetcher: Fetch = fetch) {
}),
account: (token: string) => request<Account>(fetcher, `${base}/api/cli/account`, session(token)),
signOut: (token: string) => request<void>(fetcher, `${base}/api/cli/sign-out`, session(token, { method: "POST" })),
device: (token: string, input: { workspaceId: string; id?: string; label: string; rename?: boolean }) =>
device: (token: string, input: { workspaceId?: string; id?: string; label: string; rename?: boolean }) =>
request<{ id: string; label: string }>(
fetcher,
`${base}/api/cli/device`,
session(token, { method: "POST", body: JSON.stringify(input) }),
),
agents: (token: string, workspaceId: string, deviceId: string) =>
agents: (token: string, workspaceId: string | undefined, deviceId: string) =>
request<{ agents: { id: string; label: string }[] }>(
fetcher,
`${base}/api/cli/agents?${new URLSearchParams({ workspaceId, deviceId })}`,
`${base}/api/cli/agents${query({ workspaceId, deviceId })}`,
session(token),
),
addAgent: (token: string, input: { workspaceId: string; deviceId: string; label: string }) =>
addAgent: (token: string, input: { workspaceId?: string; deviceId: string; label: string }) =>
request<{ id: string; label: string; token: string }>(
fetcher,
`${base}/api/cli/agents`,
session(token, { method: "POST", body: JSON.stringify(input) }),
),
removeAgent: (token: string, workspaceId: string, id: string) =>
removeAgent: (token: string, workspaceId: string | undefined, id: string) =>
request<void>(
fetcher,
`${base}/api/cli/agents/${encodeURIComponent(id)}?${new URLSearchParams({ workspaceId })}`,
`${base}/api/cli/agents/${encodeURIComponent(id)}${query({ workspaceId })}`,
session(token, { method: "DELETE" }),
),
};
Expand Down
80 changes: 61 additions & 19 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import { homedir } from "node:os";
import { resolve } from "node:path";
import { createApi } from "./api.js";
import { renderCard, shareText, shareUrl } from "./card.js";
import { type Context, login, logout, proxy, setup, UserError } from "./commands.js";
import { type Context, login, logout, proxy, setup, status, UserError, whoami } from "./commands.js";
import { runFix } from "./fix.js";
import { audit } from "./index.js";
import { redact, renderJson, renderReport, style } from "./report.js";
Expand All @@ -17,8 +17,13 @@ Usage
npx toolstile audit --fix Review suggested fixes and apply the ones you pick
npx toolstile auth login Sign in, from any machine, with a code
npx toolstile auth logout Sign out on this machine
npx toolstile auth status List the servers this machine is signed in to
npx toolstile whoami Show the account on the current server
npx toolstile mcp setup Choose which agents here use Toolstile

The auth, whoami and mcp commands work with Toolstile Cloud (the default), a
self-hosted server (--server <url>) or the server on this machine (--local).

Run toolstile <command> --help for a command's options.
-h, --help Show this help
-v, --version Show the version
Expand Down Expand Up @@ -64,16 +69,37 @@ Options
const AUTH_HELP = `toolstile auth: sign the CLI in to Toolstile

Usage
npx toolstile auth login [--server <url>] [--no-browser]
npx toolstile auth logout
npx toolstile auth login [--server <url> | --local] [--no-browser]
npx toolstile auth logout [--server <url> | --local | --all]
npx toolstile auth status [--json]
npx toolstile whoami [--server <url> | --local] [--json]

login prints a link and a code. Open the link on any device with a browser
(your laptop, your phone), sign in and approve the code. Nothing has to
reach this machine, so it works over SSH and on servers without a browser.

The CLI keeps one sign-in per server. The last server you signed in to is the
current one; commands use it unless --server, --local or TOOLSTILE_SERVER
picks another. logout signs out of the current server, status lists every
saved sign-in and whoami shows the account on the current server.

Servers
Toolstile Cloud https://app.toolstile.com (the default)
Self-hosted --server https://toolstile.example.com
On this machine --local: the origin in instance.json in
TOOLSTILE_DATA_DIR (default ~/.local/share/toolstile),
else http://127.0.0.1:4310
Plain http:// works only for localhost, 127.0.0.0/8 and [::1].

Options
--server <url> Toolstile address (default https://app.toolstile.com, or TOOLSTILE_URL)
--no-browser Do not try to open a browser on this machine
--server <url> Use this Toolstile server
--local Use the self-hosted server on this machine
--no-browser login: do not try to open a browser on this machine
--all logout: sign out of every server
--json status, whoami: print JSON

Environment
TOOLSTILE_SERVER Server to use when no flag picks one (TOOLSTILE_URL also works)
`;

const MCP_HELP = `toolstile mcp: connect the agents on this machine to Toolstile
Expand All @@ -84,21 +110,28 @@ Usage

setup lists the agents found here and lets you turn each one on or off.
It signs in first, the same way as auth login, when this machine is not
signed in to the server yet. Each enabled agent gets its own access, shown
signed in to the server yet. Each agent uses one server; agents on this
machine can use different servers. Each enabled agent gets its own access, shown
under this device in the Toolstile dashboard. Its config runs
\`toolstile mcp proxy\`, which holds the agent's token in the CLI's own
owner-only credentials file, so no secret is written into the agent's config.

Options for setup
--enable <agents> Turn these on without prompting (comma-separated)
--disable <agents> Turn these off without prompting
--workspace <slug> Workspace the agents use (default: the last one, or personal)
--workspace <slug> Toolstile Cloud workspace the agents use (default: the
last one, or personal); self-hosted servers have none
--device-name <name> Name for this machine (default: its hostname)
--server <url> Toolstile address (default https://app.toolstile.com, or
TOOLSTILE_URL); signs in again if this machine is signed
in to another one
--server <url> Use this server (default: the current one, or
TOOLSTILE_SERVER); signs in if needed
--local Use the self-hosted server on this machine
--switch Move agents that use another server to this one
without asking (needed without a terminal)
--no-browser Do not try to open a browser when signing in

proxy always talks to the server that issued the agent's token; --server,
--local and TOOLSTILE_SERVER do not change it.

Agents: claude-code, claude-desktop, cursor, codex, vscode, windsurf, devin, gemini, cline,
grok, opencode, kiro, antigravity
`;
Expand Down Expand Up @@ -228,7 +261,7 @@ function parseFlags(argv: string[], valued: string[], booleans: string[]) {
async function command(argv: string[]): Promise<number> {
const [group, action, ...rest] = argv;
const help = group === "auth" ? AUTH_HELP : MCP_HELP;
const actions = group === "auth" ? ["login", "logout"] : ["setup", "proxy"];
const actions = group === "auth" ? ["login", "logout", "status", "whoami"] : ["setup", "proxy"];
if (!action || action === "-h" || action === "--help" || action === "help") {
process.stdout.write(help);
return action ? 0 : 2;
Expand All @@ -253,27 +286,35 @@ async function command(argv: string[]): Promise<number> {
try {
const flags =
action === "login"
? parseFlags(rest, ["server"], ["no-browser"])
? parseFlags(rest, ["server"], ["local", "no-browser"])
: action === "logout"
? parseFlags(rest, [], [])
: action === "setup"
? parseFlags(rest, ["enable", "disable", "workspace", "device-name", "server"], ["no-browser"])
: parseFlags(rest, ["agent"], []);
? parseFlags(rest, ["server"], ["local", "all"])
: action === "status"
? parseFlags(rest, [], ["json"])
: action === "whoami"
? parseFlags(rest, ["server"], ["local", "json"])
: action === "setup"
? parseFlags(rest, ["enable", "disable", "workspace", "device-name", "server"], ["no-browser", "local", "switch"])
: parseFlags(rest, ["agent"], []);
if (flags === "help") {
process.stdout.write(help);
return 0;
}
const value = (name: string) => (typeof flags[name] === "string" ? (flags[name] as string) : undefined);
if (action === "login") return await login(ctx, { server: value("server"), browser: !flags["no-browser"] });
if (action === "logout") return await logout(ctx);
const target = { server: value("server"), local: flags.local === true };
if (action === "login") return await login(ctx, { ...target, browser: !flags["no-browser"] });
if (action === "logout") return await logout(ctx, { ...target, all: flags.all === true });
if (action === "status") return status(ctx, { json: flags.json === true });
if (action === "whoami") return whoami(ctx, { ...target, json: flags.json === true });
if (action === "setup")
return await setup(ctx, {
enable: value("enable"),
disable: value("disable"),
workspace: value("workspace"),
deviceName: value("device-name"),
server: value("server"),
...target,
browser: !flags["no-browser"],
switch: flags.switch === true,
});
return await proxy(ctx, value("agent"));
} catch (error) {
Expand All @@ -287,6 +328,7 @@ async function command(argv: string[]): Promise<number> {

async function main(): Promise<number> {
const argv = process.argv.slice(2);
if (argv[0] === "whoami") return command(["auth", ...argv]);
if (argv[0] === "auth" || argv[0] === "mcp") return command(argv);
const help = argv[0] === "audit" ? AUDIT_HELP : HELP;
let args: ReturnType<typeof parseArgs>;
Expand Down
Loading