@togglhq/cli 1.11.226 → 1.12.0

package/README.md

@@ -31,6 +31,18 @@ Opens a browser for OAuth sign-in. On success, credentials are saved to `~/.togg
 
 Sessions refresh automatically. Re-run `toggl auth` only to switch workspaces or after 4 weeks of inactivity.
 
+### API key (CI or headless)
+
+Set `TOGGL_API_TOKEN` to a personal API key (`toggl_sk_…`, from Toggl 2.0 **Settings → API token**). It takes precedence over saved profiles; nothing opens a browser or writes to `~/.toggl/focus-tools.json`.
+
+```bash
+export TOGGL_API_TOKEN=toggl_sk_...
+export TOGGL_ORGANIZATION_ID=4364968   # usually required: API keys cannot list organizations
+toggl tasks list
+```
+
+`TOGGL_WORKSPACE_ID` (default: your current Toggl 2.0 workspace) and `TOGGL_USER_ID` (default: looked up from the key) are optional; `--workspace-id` overrides `TOGGL_WORKSPACE_ID`. `organization …` and `shared …` commands call Toggl Accounts, which does not accept API keys, so they ask you to unset the variable and run `toggl auth`. Profile and workspace switching are disabled in this mode.
+
 ## Profiles
 
 Use profiles to switch between saved accounts and environments:

package/build/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as CommanderError, i as shutdownCliTelemetry, n as captureCliException, r as initCliTelemetry, t as createProgram } from "./program-BB9t7xvO.js";
+import { a as CommanderError, i as shutdownCliTelemetry, n as captureCliException, r as initCliTelemetry, t as createProgram } from "./program-BLPqhZj7.js";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";

package/build/index.d.ts

@@ -1,2 +1,2 @@
-import { t as createProgram } from "./program-Bby4U_hT.js";
+import { n as createProgram } from "./program-CxOdqdfD.js";
 export { createProgram };

package/build/index.js

@@ -1,2 +1,2 @@
-import { t as createProgram } from "./program-BB9t7xvO.js";
+import { t as createProgram } from "./program-BLPqhZj7.js";
 export { createProgram };

package/build/{program-BB9t7xvO.js → program-BLPqhZj7.js}

@@ -5204,104 +5204,6 @@ var dist_default = createPrompt((config, done) => {
 	].filter(Boolean).join("\n").trimEnd()}${cursorHide}`;
 });
 //#endregion
-//#region ../cli-core/build/profile-Empu4JWK.js
-const CONFIG_DIR = path$1.join(os.homedir(), ".toggl");
-const CONFIG_FILE = path$1.join(CONFIG_DIR, "focus-tools.json");
-const LEGACY_MCP_CONFIG_FILE = path$1.join(os.homedir(), ".toggl-focus-mcp", "config.json");
-function readJsonFile(filePath) {
-	if (!fs$1.existsSync(filePath)) return null;
-	try {
-		return JSON.parse(fs$1.readFileSync(filePath, "utf-8"));
-	} catch (err) {
-		const msg = err instanceof Error ? err.message : String(err);
-		throw new Error(`Failed to read ${filePath}: ${msg}`, { cause: err });
-	}
-}
-function saveLegacyAuthConfig(config) {
-	const dir = path$1.dirname(LEGACY_MCP_CONFIG_FILE);
-	fs$1.mkdirSync(dir, { recursive: true });
-	const tmp = `${LEGACY_MCP_CONFIG_FILE}.${process.pid}.tmp`;
-	fs$1.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
-	fs$1.renameSync(tmp, LEGACY_MCP_CONFIG_FILE);
-}
-function loadDeveloperToolsConfig() {
-	const config = readJsonFile(CONFIG_FILE);
-	if (!config || !config.profiles) return null;
-	return config;
-}
-function loadProfile(scope = "cli", profile) {
-	const config = loadDeveloperToolsConfig();
-	if (config) {
-		const activeProfile = profile ?? config.active[scope];
-		if (activeProfile && config.profiles[activeProfile]) return config.profiles[activeProfile];
-	}
-	const legacy = readJsonFile(LEGACY_MCP_CONFIG_FILE);
-	if (!legacy?.access_token || !legacy.workspace_id) return null;
-	return legacy;
-}
-function saveDeveloperToolsConfig(config) {
-	fs$1.mkdirSync(CONFIG_DIR, { recursive: true });
-	const tmp = `${CONFIG_FILE}.${process.pid}.tmp`;
-	fs$1.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
-	fs$1.renameSync(tmp, CONFIG_FILE);
-}
-function profileEnvironment(focusApiUrl) {
-	const hostname = new URL(focusApiUrl).hostname;
-	if (hostname === "focus.toggl.com") return "production";
-	return hostname.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").toLowerCase();
-}
-function profileSlug(value, fallback) {
-	return (value?.split("@")[0] ?? fallback).normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").toLowerCase() || fallback;
-}
-function deriveCliProfileName(options) {
-	return `${profileSlug(options.email, "user")}-${options.userId}`;
-}
-function toProfileRow(name, auth, activeProfile) {
-	const workspace = auth.workspaces?.find((candidate) => candidate.workspace_id === auth.workspace_id);
-	return {
-		name,
-		active: name === activeProfile,
-		environment: profileEnvironment(auth.focus_api_url),
-		user_id: auth.user_id,
-		organization_id: auth.organization_id,
-		organization_name: workspace?.organization_name,
-		workspace_id: auth.workspace_id,
-		workspace_name: auth.workspace_name,
-		focus_api_url: auth.focus_api_url,
-		accounts_api_url: auth.accounts_api_url,
-		authenticated_at: auth.authenticated_at,
-		expires_at: auth.expires_at,
-		token_expired: auth.expires_at <= Date.now() / 1e3
-	};
-}
-function listCliProfiles() {
-	const config = loadDeveloperToolsConfig();
-	if (!config?.profiles) return [];
-	return Object.entries(config.profiles).map(([name, auth]) => toProfileRow(name, auth, config.active.cli)).sort((a, b) => a.name.localeCompare(b.name));
-}
-function getCurrentCliProfile() {
-	const config = loadDeveloperToolsConfig();
-	const activeProfile = config?.active.cli;
-	if (!config?.profiles || !activeProfile || !config.profiles[activeProfile]) throw new Error("No active CLI profile. Run `toggl auth` to sign in.");
-	return toProfileRow(activeProfile, config.profiles[activeProfile], activeProfile);
-}
-function switchCliProfile(profileName) {
-	const config = loadDeveloperToolsConfig();
-	if (!config?.profiles?.[profileName]) throw new Error(`Profile '${profileName}' not found. Run \`toggl profile list\` to see profiles.`);
-	config.active.cli = profileName;
-	saveDeveloperToolsConfig(config);
-	return toProfileRow(profileName, config.profiles[profileName], profileName);
-}
-function removeCliProfile(profileName) {
-	const config = loadDeveloperToolsConfig();
-	if (!config?.profiles?.[profileName]) throw new Error(`Profile '${profileName}' not found. Run \`toggl profile list\` to see profiles.`);
-	const removed = toProfileRow(profileName, config.profiles[profileName], config.active.cli);
-	delete config.profiles[profileName];
-	if (config.active.cli === profileName) config.active.cli = Object.keys(config.profiles).sort()[0];
-	saveDeveloperToolsConfig(config);
-	return removed;
-}
-//#endregion
 //#region ../cli-core/build/env-CiVJIUnv.js
 const PRODUCTION_URLS = {
 	focusApiUrl: "https://focus.toggl.com",
@@ -11038,7 +10940,7 @@ async function deleteMyWorkingHours(httpClient, organization_id, data, signal) {
 	return response.json();
 }
 //#endregion
-//#region ../cli-core/build/focus-client-D9JzuIl3.js
+//#region ../cli-core/build/focus-client-CGUlmnDg.js
 /** Request header the API reads to attribute traffic to MCP or CLI. */
 const TOGGL_CLIENT_HEADER = "X-Toggl-Client";
 /** Header the Focus API reads for analytics and presence `platform_origin`. */
@@ -12018,7 +11920,313 @@ var FocusClient = class {
 	}
 };
 //#endregion
+//#region ../cli-core/build/profile-BNQd2PG5.js
+const CONFIG_DIR = path$1.join(os.homedir(), ".toggl");
+const CONFIG_FILE = path$1.join(CONFIG_DIR, "focus-tools.json");
+const LEGACY_MCP_CONFIG_FILE = path$1.join(os.homedir(), ".toggl-focus-mcp", "config.json");
+function readJsonFile(filePath) {
+	if (!fs$1.existsSync(filePath)) return null;
+	try {
+		return JSON.parse(fs$1.readFileSync(filePath, "utf-8"));
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to read ${filePath}: ${msg}`, { cause: err });
+	}
+}
+function saveLegacyAuthConfig(config) {
+	const dir = path$1.dirname(LEGACY_MCP_CONFIG_FILE);
+	fs$1.mkdirSync(dir, { recursive: true });
+	const tmp = `${LEGACY_MCP_CONFIG_FILE}.${process.pid}.tmp`;
+	fs$1.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
+	fs$1.renameSync(tmp, LEGACY_MCP_CONFIG_FILE);
+}
+function loadDeveloperToolsConfig() {
+	const config = readJsonFile(CONFIG_FILE);
+	if (!config || !config.profiles) return null;
+	return config;
+}
+function loadProfile(scope = "cli", profile) {
+	const config = loadDeveloperToolsConfig();
+	if (config) {
+		const activeProfile = profile ?? config.active[scope];
+		if (activeProfile && config.profiles[activeProfile]) return config.profiles[activeProfile];
+	}
+	const legacy = readJsonFile(LEGACY_MCP_CONFIG_FILE);
+	if (!legacy?.access_token || !legacy.workspace_id) return null;
+	return legacy;
+}
+function saveDeveloperToolsConfig(config) {
+	fs$1.mkdirSync(CONFIG_DIR, { recursive: true });
+	const tmp = `${CONFIG_FILE}.${process.pid}.tmp`;
+	fs$1.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
+	fs$1.renameSync(tmp, CONFIG_FILE);
+}
+function profileEnvironment(focusApiUrl) {
+	const hostname = new URL(focusApiUrl).hostname;
+	if (hostname === "focus.toggl.com") return "production";
+	return hostname.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+}
+function profileSlug(value, fallback) {
+	return (value?.split("@")[0] ?? fallback).normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").toLowerCase() || fallback;
+}
+function deriveCliProfileName(options) {
+	return `${profileSlug(options.email, "user")}-${options.userId}`;
+}
+function toProfileRow(name, auth, activeProfile) {
+	const workspace = auth.workspaces?.find((candidate) => candidate.workspace_id === auth.workspace_id);
+	return {
+		name,
+		active: name === activeProfile,
+		environment: profileEnvironment(auth.focus_api_url),
+		user_id: auth.user_id,
+		organization_id: auth.organization_id,
+		organization_name: workspace?.organization_name,
+		workspace_id: auth.workspace_id,
+		workspace_name: auth.workspace_name,
+		focus_api_url: auth.focus_api_url,
+		accounts_api_url: auth.accounts_api_url,
+		authenticated_at: auth.authenticated_at,
+		expires_at: auth.expires_at,
+		token_expired: auth.expires_at <= Date.now() / 1e3
+	};
+}
+function listCliProfiles() {
+	const config = loadDeveloperToolsConfig();
+	if (!config?.profiles) return [];
+	return Object.entries(config.profiles).map(([name, auth]) => toProfileRow(name, auth, config.active.cli)).sort((a, b) => a.name.localeCompare(b.name));
+}
+function getCurrentCliProfile() {
+	const config = loadDeveloperToolsConfig();
+	const activeProfile = config?.active.cli;
+	if (!config?.profiles || !activeProfile || !config.profiles[activeProfile]) throw new Error("No active CLI profile. Run `toggl auth` to sign in.");
+	return toProfileRow(activeProfile, config.profiles[activeProfile], activeProfile);
+}
+function switchCliProfile(profileName) {
+	const config = loadDeveloperToolsConfig();
+	if (!config?.profiles?.[profileName]) throw new Error(`Profile '${profileName}' not found. Run \`toggl profile list\` to see profiles.`);
+	config.active.cli = profileName;
+	saveDeveloperToolsConfig(config);
+	return toProfileRow(profileName, config.profiles[profileName], profileName);
+}
+function removeCliProfile(profileName) {
+	const config = loadDeveloperToolsConfig();
+	if (!config?.profiles?.[profileName]) throw new Error(`Profile '${profileName}' not found. Run \`toggl profile list\` to see profiles.`);
+	const removed = toProfileRow(profileName, config.profiles[profileName], config.active.cli);
+	delete config.profiles[profileName];
+	if (config.active.cli === profileName) config.active.cli = Object.keys(config.profiles).sort()[0];
+	saveDeveloperToolsConfig(config);
+	return removed;
+}
+//#endregion
 //#region ../cli-core/build/index.js
+/**
+* Headless auth with a personal Toggl API key (`toggl_sk_…`).
+*
+* When `TOGGL_API_TOKEN` is set it wins over any OAuth profile: no browser, no
+* refresh, and nothing is written to `~/.toggl/focus-tools.json`. The key is sent
+* to the Toggl 2.0 API as `Authorization: Bearer toggl_sk_…`. The API never falls
+* back to session auth once a key is presented, so a bad key is a hard 401.
+*
+* API-key requests carry no Accounts session. Toggl Accounts itself only accepts
+* OAuth/session credentials, so anything that calls Accounts directly (the `org`
+* and `shared` operation families) needs an OAuth sign-in instead.
+*/
+const TOGGL_API_TOKEN_ENV = "TOGGL_API_TOKEN";
+const TOGGL_USER_ID_ENV = "TOGGL_USER_ID";
+const TOGGL_WORKSPACE_ID_ENV = "TOGGL_WORKSPACE_ID";
+const TOGGL_ORGANIZATION_ID_ENV = "TOGGL_ORGANIZATION_ID";
+/** Matches `apikey.KeyPrefix` in toggl/pkg. */
+const TOGGL_API_KEY_PREFIX = "toggl_sk_";
+const REDACTED_API_TOKEN = `${TOGGL_API_KEY_PREFIX}[REDACTED]`;
+var ApiTokenAuthError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.name = "ApiTokenAuthError";
+		this.status = status;
+	}
+};
+/** The raw `TOGGL_API_TOKEN` value, trimmed; blank counts as unset. */
+function readApiTokenFromEnv(env = process.env) {
+	const value = env[TOGGL_API_TOKEN_ENV]?.trim();
+	return value ? value : void 0;
+}
+/** True whenever `TOGGL_API_TOKEN` is set, valid or not: a bad key must fail, not fall back to OAuth. */
+function isApiTokenMode(env = process.env) {
+	return readApiTokenFromEnv(env) !== void 0;
+}
+/** Returns the key, or throws without ever echoing the value back. */
+function requireApiToken(env = process.env) {
+	const token = readApiTokenFromEnv(env);
+	if (!token) throw new ApiTokenAuthError(`${TOGGL_API_TOKEN_ENV} is not set.`);
+	if (!token.startsWith("toggl_sk_")) throw new ApiTokenAuthError(`${TOGGL_API_TOKEN_ENV} is not a Toggl API key: keys start with "${TOGGL_API_KEY_PREFIX}". Create one in Toggl 2.0 under Settings → API token.`);
+	return token;
+}
+const API_KEY_PATTERN = new RegExp(`${TOGGL_API_KEY_PREFIX}[^\\s"'\`,;)}\\]]*`, "g");
+/** Replace every `toggl_sk_…` key, plus the configured token verbatim, in free text. */
+function redactApiTokens(text, env = process.env) {
+	let redacted = text.replace(API_KEY_PATTERN, REDACTED_API_TOKEN);
+	const token = readApiTokenFromEnv(env);
+	if (token && token.length >= 8) redacted = redacted.split(token).join(REDACTED_API_TOKEN);
+	return redacted;
+}
+/** Deep-redact API keys in every string of a JSON-like value, in place where possible. */
+function redactApiTokensDeep(value, env = process.env) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	const visit = (node) => {
+		if (typeof node === "string") return redactApiTokens(node, env);
+		if (!node || typeof node !== "object") return node;
+		if (seen.has(node)) return node;
+		seen.add(node);
+		if (Array.isArray(node)) {
+			for (let i = 0; i < node.length; i++) node[i] = visit(node[i]);
+			return node;
+		}
+		const record = node;
+		for (const key of Object.keys(record)) record[key] = visit(record[key]);
+		return node;
+	};
+	return visit(value);
+}
+function parseIdEnv(env, name) {
+	const raw = env[name]?.trim();
+	if (!raw) return void 0;
+	if (!/^\d+$/.test(raw)) throw new ApiTokenAuthError(`${name} must be a positive integer.`);
+	const id = Number(raw);
+	if (id <= 0 || id > Number.MAX_SAFE_INTEGER) throw new ApiTokenAuthError(`${name} must be a positive integer.`);
+	return id;
+}
+function positiveId(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : void 0;
+}
+function focusApiBase(focusApiUrl) {
+	const trimmed = focusApiUrl.replace(/\/+$/, "");
+	return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;
+}
+const INVALID_KEY_MESSAGE = `Toggl rejected ${TOGGL_API_TOKEN_ENV} (401). The key may have been revoked or replaced — creating a new key invalidates the previous one. Create a fresh key in Toggl 2.0 under Settings → API token.`;
+async function getJson(url, token, options) {
+	const doFetch = options.fetch ?? fetch;
+	const timeoutMs = options.timeoutMs ?? 1e4;
+	const origin = new URL(url).origin;
+	try {
+		const response = await doFetch(url, {
+			headers: {
+				Authorization: `Bearer ${token}`,
+				Accept: "application/json",
+				...togglClientHeaders(options.clientSurface)
+			},
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+		if (!response.ok) return { status: response.status };
+		return {
+			status: response.status,
+			body: await response.json()
+		};
+	} catch (error) {
+		if (error instanceof DOMException && error.name === "TimeoutError") throw new ApiTokenAuthError(`The Toggl 2.0 API at ${origin} did not answer within ${Math.round(timeoutMs / 1e3)}s.`);
+		if (error instanceof SyntaxError) throw new ApiTokenAuthError(`The Toggl 2.0 API at ${origin} returned a response that is not JSON.`);
+		throw new ApiTokenAuthError(`Could not reach the Toggl 2.0 API at ${origin}: ${redactApiTokens(error instanceof Error ? error.message : String(error), options.env)}`);
+	}
+}
+/**
+* Work out the user, workspace and organization the key acts in.
+*
+* Explicit values win (`--workspace-id`, then `TOGGL_*_ID`). Otherwise:
+* - user: `GET /api/accounts/me` → `user_account_id`
+* - workspace: `GET /api/users/me/settings` → `current_workspace_id`, then the
+*   workspace last picked in Toggl's hosted MCP
+* - organization: the hosted-MCP selection when it names the same workspace.
+*   The Toggl 2.0 API has no "my organizations" endpoint an API key can read,
+*   so any other case needs `TOGGL_ORGANIZATION_ID`.
+*
+* The settings call always runs, so a revoked key fails here rather than on the
+* first tool call. The chosen pair is then checked with one org+workspace-scoped
+* read, which is what turns a wrong or foreign organization into a clear error.
+*/
+async function resolveApiTokenIdentity(options) {
+	const env = options.env ?? process.env;
+	const token = requireApiToken(env);
+	const api = focusApiBase(options.focusApiUrl);
+	const envUserId = parseIdEnv(env, TOGGL_USER_ID_ENV);
+	const envWorkspaceId = parseIdEnv(env, TOGGL_WORKSPACE_ID_ENV);
+	const envOrganizationId = parseIdEnv(env, TOGGL_ORGANIZATION_ID_ENV);
+	const settings = await getJson(`${api}/users/me/settings`, token, options);
+	if (settings.status === 401) throw new ApiTokenAuthError(INVALID_KEY_MESSAGE, 401);
+	if (!settings.body) throw new ApiTokenAuthError(`Could not read your Toggl 2.0 user settings (${settings.status}).`, settings.status);
+	let userId = envUserId;
+	let userSource = "env";
+	if (userId === void 0) {
+		const me = await getJson(`${api}/accounts/me`, token, options);
+		if (me.status === 401) throw new ApiTokenAuthError(INVALID_KEY_MESSAGE, 401);
+		userId = positiveId(me.body?.user_account_id);
+		if (userId === void 0) throw new ApiTokenAuthError(`Could not determine your Toggl user ID (${me.status}). Set ${TOGGL_USER_ID_ENV}.`, me.status);
+		userSource = "api";
+	}
+	const hostedMcpWorkspaceId = positiveId(settings.body.mcp_active_workspace_id);
+	const hostedMcpOrganizationId = positiveId(settings.body.mcp_active_organization_id);
+	let workspaceId;
+	let workspaceSource;
+	if (options.workspaceIdOverride !== void 0) {
+		workspaceId = options.workspaceIdOverride;
+		workspaceSource = "flag";
+	} else if (envWorkspaceId !== void 0) {
+		workspaceId = envWorkspaceId;
+		workspaceSource = "env";
+	} else {
+		workspaceId = positiveId(settings.body.current_workspace_id) ?? hostedMcpWorkspaceId;
+		workspaceSource = "api";
+	}
+	if (workspaceId === void 0) throw new ApiTokenAuthError(`Could not determine a workspace: your Toggl 2.0 settings have no current workspace. Set ${TOGGL_WORKSPACE_ID_ENV}.`);
+	let organizationId = envOrganizationId;
+	let organizationSource = "env";
+	if (organizationId === void 0) if (hostedMcpOrganizationId !== void 0 && hostedMcpWorkspaceId === workspaceId) {
+		organizationId = hostedMcpOrganizationId;
+		organizationSource = "api";
+	} else throw new ApiTokenAuthError(`Could not determine the organization for workspace ${workspaceId}: API keys cannot list organizations. Set ${TOGGL_ORGANIZATION_ID_ENV} (app URLs read focus.toggl.com/<organization_id>/workspaces/<workspace_id>/…).`);
+	const probe = await getJson(`${api}/organizations/${organizationId}/workspaces/${workspaceId}/custom-fields`, token, options);
+	if (probe.status === 401) throw new ApiTokenAuthError(INVALID_KEY_MESSAGE, 401);
+	if (probe.status === 403 || probe.status === 404) throw new ApiTokenAuthError(`This API key has no access to workspace ${workspaceId} in organization ${organizationId}. Check ${TOGGL_ORGANIZATION_ID_ENV} and ${TOGGL_WORKSPACE_ID_ENV}.`, probe.status);
+	if (probe.status >= 400) throw new ApiTokenAuthError(`Could not verify access to workspace ${workspaceId} in organization ${organizationId} (${probe.status}).`, probe.status);
+	return {
+		user_id: userId,
+		organization_id: organizationId,
+		workspace_id: workspaceId,
+		focus_api_url: options.focusApiUrl,
+		accounts_api_url: options.accountsApiUrl,
+		sources: {
+			user_id: userSource,
+			organization_id: organizationSource,
+			workspace_id: workspaceSource
+		}
+	};
+}
+function createApiTokenIdentityCache(options) {
+	let resolved;
+	let pending;
+	let failure;
+	return {
+		resolve() {
+			if (resolved) return Promise.resolve(resolved);
+			pending ??= resolveApiTokenIdentity(options()).then((identity) => {
+				resolved = identity;
+				failure = void 0;
+				return identity;
+			}).catch((error) => {
+				failure = error instanceof Error ? error.message : String(error);
+				throw error;
+			}).finally(() => {
+				pending = void 0;
+			});
+			return pending;
+		},
+		peek: () => resolved,
+		lastError: () => failure
+	};
+}
+/** Text every OAuth-only surface returns while `TOGGL_API_TOKEN` is set. */
+function oauthRequiredMessage(subject, authCommand) {
+	return `${subject} requires OAuth sign-in (run auth): it calls Toggl Accounts, which does not accept API keys. Unset ${TOGGL_API_TOKEN_ENV} and run \`${authCommand}\` to use it.`;
+}
 function openAuthBrowser(url) {
 	const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start \"\"" : "xdg-open";
 	exec(`${cmd} "${url}"`, (err) => {
@@ -12643,6 +12851,7 @@ async function refreshTokens(accountsApiUrl, refreshToken, clientSurface, client
 	return response.json();
 }
 async function getValidToken(scope = "cli", profile) {
+	if (isApiTokenMode()) return requireApiToken();
 	const authConfig = loadProfile(scope, profile);
 	if (!authConfig) throw new Error(scope === "cli" ? "Not authenticated. Run `toggl auth` to sign in." : `Not authenticated. Run \`${npxMcpAuthCommand()}\` to sign in.`);
 	const now = Date.now() / 1e3;
@@ -12862,7 +13071,7 @@ function scrubSpan(span) {
 /**
 * Last word on every event the public build sends: messages reduced to fixed
 * categories, no hostname, no breadcrumbs, no dependency list, no request data,
-* package-relative stack paths, and no query strings on spans.
+* package-relative stack paths, no query strings on spans, and no API keys.
 */
 function scrubPublicSentryEvent(event) {
 	redactUnsafeSentryMessages(event);
@@ -12874,7 +13083,7 @@ function scrubPublicSentryEvent(event) {
 	for (const thread of event.threads?.values ?? []) scrubStacktrace(thread.stacktrace);
 	for (const span of event.spans ?? []) scrubSpan(span);
 	scrubSpan(event.contexts?.trace);
-	return event;
+	return redactApiTokensDeep(event);
 }
 /**
 * Privacy options shared by `initCliTelemetry` and `initPublicSentry`.
@@ -13056,6 +13265,7 @@ function decodeAccessTokenSubject(token) {
 * from every other identity we already have for the same user.
 */
 function resolveProductAnalyticsDistinctId(scope) {
+	if (isApiTokenMode()) return null;
 	try {
 		return decodeAccessTokenSubject(loadProfile(scope)?.access_token);
 	} catch {
@@ -13156,7 +13366,7 @@ async function runSkillSetup(options) {
 	});
 }
 //#endregion
-//#region ../operations/build/validation-Byte2z0O.js
+//#region ../operations/build/validation-Cl22AQf7.js
 const optionalNumber = /* @__PURE__ */ optional$1(/* @__PURE__ */ number$2());
 const perPageField = (max) => /* @__PURE__ */ optional$1(/* @__PURE__ */ pipe$2(/* @__PURE__ */ number$2(), /* @__PURE__ */ integer(), /* @__PURE__ */ minValue$1(1), /* @__PURE__ */ maxValue$1(max), /* @__PURE__ */ description$1(`Results per page (1-${max})`)));
 const perPageSchema = perPageField(100);
@@ -14552,6 +14762,14 @@ const orgSharedOperations = [
 function operationRequiresExplicitAcknowledgment(operation) {
 	return operation.destructive;
 }
+/**
+* `org` and `shared` operations call Toggl Accounts directly, and Accounts only
+* accepts OAuth/session credentials. With `TOGGL_API_TOKEN` they cannot work, so
+* both surfaces short-circuit them with a sign-in message instead of a 401.
+*/
+function operationRequiresOAuth(operation) {
+	return operation.family === "org" || operation.family === "shared";
+}
 const MAX_ERROR_LENGTH = 200;
 const MAX_RECEIVED_LENGTH = 40;
 function formatIssueMessage(issue) {
@@ -27929,6 +28147,17 @@ function filterRowsByQuerySlice(rows, query) {
 	const q = query.trim().toLowerCase();
 	return (q.length === 0 ? rows : rows.filter((r) => r.name.toLowerCase().includes(q) || (r.description?.toLowerCase().includes(q) ?? false) || String(r.value).includes(q))).slice(0, 25);
 }
+/** Pickers listed from Toggl Accounts, which rejects `TOGGL_API_TOKEN` keys. */
+const ACCOUNTS_BACKED_PICKERS = new Set(["org_workspace"]);
+/**
+* The picker to offer for a prompt path, or null for plain ID input. With an API key the
+* Accounts-backed pickers would only fail with a 401, so the prompt asks for IDs directly.
+*/
+function usableEntityKindForPromptPath(path, env = process.env) {
+	const kind = entityKindForPromptPath(path);
+	if (kind && isApiTokenMode(env) && ACCOUNTS_BACKED_PICKERS.has(kind)) return null;
+	return kind;
+}
 function entityKindForPromptPath(path) {
 	const leaf = path.split(".").pop() ?? path;
 	if (leaf === "project_id") return "project";
@@ -28243,7 +28472,7 @@ async function promptForField(field, adapter, entityContext) {
 		default: false
 	});
 	if (field.type === "number") {
-		const entityKind = entityKindForPromptPath(field.path);
+		const entityKind = usableEntityKindForPromptPath(field.path);
 		if (entityContext && entityKind && adapter.searchNumber) {
 			const source = createEntitySearchSource(entityKind, entityContext);
 			const wrappedSource = async (term, opt) => {
@@ -28270,7 +28499,7 @@ async function promptForField(field, adapter, entityContext) {
 	}
 	if (field.type === "array") {
 		if (field.itemSchema) return promptArrayOfObjectItems(field, adapter, entityContext);
-		const arrayEntityKind = field.itemType === "number" ? entityKindForPromptPath(field.path) : null;
+		const arrayEntityKind = field.itemType === "number" ? usableEntityKindForPromptPath(field.path) : null;
 		if (entityContext && arrayEntityKind) {
 			let query;
 			for (;;) {
@@ -28637,7 +28866,7 @@ async function runValidatedOperation(operation, options, deps) {
 		return;
 	}
 	if (operationRequiresExplicitAcknowledgment(operation) && !options.yes) throw new Error(`${operation.id} is a destructive operation. Pass --yes to confirm, or --dry-run to preview.`);
-	const response = await operation.execute(input, { client: deps.getClient() });
+	const response = await operation.execute(input, { client: await deps.getClient() });
 	if (!response.ok) throw new Error(`${response.status}: ${response.message}`);
 	deps.output(response.data);
 }
@@ -29015,7 +29244,68 @@ function outputJson(data, globalOptions) {
 	if (globalOptions.json) process.stdout.write(JSON.stringify(data, null, 2) + "\n");
 	else process.stdout.write(JSON.stringify(data, null, 2) + "\n");
 }
-function getClient(options) {
+const CLI_API_TOKEN_PROFILES_MESSAGE = "Saved profiles are not used while TOGGL_API_TOKEN is set: every command authenticates with the API key. Unset TOGGL_API_TOKEN to use OAuth profiles again.";
+const CLI_API_TOKEN_WORKSPACE_MESSAGE = "While TOGGL_API_TOKEN is set the workspace comes from --workspace-id, TOGGL_WORKSPACE_ID and TOGGL_ORGANIZATION_ID (or your Toggl 2.0 current workspace).";
+/**
+* Resolves the API-key identity once per URL pair and `--workspace-id`, so a prompted
+* command (entity pickers, then the operation itself) does not repeat the probes.
+*/
+function createCliApiTokenResolver(resolveUrls) {
+	const caches = /* @__PURE__ */ new Map();
+	function identity(options, urls = resolveUrls()) {
+		const workspaceIdOverride = options.workspaceId ? parseWorkspaceIdArg(options.workspaceId) : void 0;
+		const key = [
+			urls.focusApiUrl,
+			urls.accountsApiUrl,
+			workspaceIdOverride ?? ""
+		].join("\n");
+		let cache = caches.get(key);
+		if (!cache) {
+			cache = createApiTokenIdentityCache(() => ({
+				focusApiUrl: urls.focusApiUrl,
+				accountsApiUrl: urls.accountsApiUrl,
+				clientSurface: "cli",
+				workspaceIdOverride
+			}));
+			caches.set(key, cache);
+		}
+		return cache.resolve();
+	}
+	async function client(options) {
+		const resolved = await identity(options);
+		return new FocusClient({
+			baseUrl: resolved.focus_api_url,
+			accountsApiUrl: resolved.accounts_api_url,
+			tokenProvider: () => getValidToken("cli"),
+			userId: resolved.user_id,
+			organizationId: String(resolved.organization_id),
+			workspaceId: String(resolved.workspace_id),
+			clientSurface: "cli"
+		});
+	}
+	return {
+		identity,
+		client
+	};
+}
+function describeCliApiTokenIdentity(identity) {
+	return {
+		auth_mode: "api_token",
+		user_id: identity.user_id,
+		organization_id: identity.organization_id,
+		workspace_id: identity.workspace_id,
+		focus_api_url: identity.focus_api_url,
+		id_sources: identity.sources
+	};
+}
+/** `org`/`shared` commands call Toggl Accounts, which rejects API keys. */
+function assertOperationAvailableInAuthMode(operation) {
+	if (!isApiTokenMode() || !operationRequiresOAuth(operation)) return;
+	const command = [...operation.cli.group, operation.cli.command].join(" ");
+	throw new Error(oauthRequiredMessage(`\`toggl ${command}\``, "toggl auth"));
+}
+function getClient(options, apiToken) {
+	if (isApiTokenMode()) return apiToken.client(options);
 	const config = loadProfile("cli", options.profile);
 	if (!config) throw new Error(`Not authenticated. Run \`toggl auth\` to sign in, or \`${npxMcpAuthCommand()}\` for a shared session.`);
 	const urls = resolveEnvironmentUrls({
@@ -29032,10 +29322,10 @@ function getClient(options) {
 		clientSurface: "cli"
 	});
 }
-async function runOperation(operation, globalOptions, options, rawInput) {
+async function runOperation(operation, globalOptions, options, apiToken, rawInput) {
 	await runValidatedOperation(operation, options, {
 		rawInput,
-		getClient: () => getClient(globalOptions),
+		getClient: () => getClient(globalOptions, apiToken),
 		output: (data) => output(data, globalOptions),
 		outputJson: (data) => outputJson(data, globalOptions)
 	});
@@ -29083,6 +29373,7 @@ function createProgram(programOptions = {}) {
 	const promptAdapter = programOptions.promptAdapter ?? inquirerPromptAdapter;
 	const isTty = programOptions.isTty ?? (() => Boolean(process.stdin.isTTY && process.stdout.isTTY));
 	const env = programOptions.env ?? process.env;
+	const apiToken = createCliApiTokenResolver(() => programOptions.resolveAuthUrls?.({}) ?? resolveEnvironmentUrls());
 	const program = new Command();
 	program.name("toggl").description("Toggl CLI — generated from the shared operation catalog").version(CLI_PACKAGE_VERSION).option("--json", "Output pretty-printed JSON").option("--profile <name>", "Use a saved auth profile").option("--workspace-id <id>", "Override the active workspace ID").exitOverride();
 	const authCommand = program.command("auth").description("Authenticate with your Toggl account");
@@ -29090,6 +29381,12 @@ function createProgram(programOptions = {}) {
 	authCommand.option("--workspace-id <id>", "Select a workspace by ID (required if you have multiple)").option("--profile <name>", "Profile name to save credentials under").option("--manual", "Headless/SSH flow: open the printed link, copy the code from accounts.toggl.com, paste here").option("--code <value>", "Authorization code from the login link (pair with --manual when not using localhost)").action(async (opts) => {
 		try {
 			const urls = programOptions.resolveAuthUrls?.(opts) ?? resolveEnvironmentUrls();
+			if (isApiTokenMode()) {
+				const identity = await apiToken.identity(program.opts(), urls);
+				process.stderr.write("TOGGL_API_TOKEN is set, so no browser sign-in runs and no profile is saved.\n");
+				output(describeCliApiTokenIdentity(identity), program.opts());
+				return;
+			}
 			const globalOpts = program.opts();
 			const workspaceId = opts.workspaceId ?? globalOpts.workspaceId;
 			const profile = opts.profile ?? globalOpts.profile;
@@ -29128,6 +29425,17 @@ function createProgram(programOptions = {}) {
 	workspaceCommand.command("list").description("Show workspaces you can use (active workspace is marked)").option("--refresh", "Re-fetch workspaces from your account").action(async (opts) => {
 		try {
 			const globalOptions = program.opts();
+			if (isApiTokenMode()) {
+				if (opts.refresh) throw new Error(oauthRequiredMessage("`toggl workspace list --refresh`", "toggl auth"));
+				const identity = await apiToken.identity(globalOptions);
+				output([{
+					workspace_id: identity.workspace_id,
+					organization_id: identity.organization_id,
+					active: true,
+					auth_mode: "api_token"
+				}], globalOptions);
+				return;
+			}
 			output(opts.refresh ? await refreshCliWorkspaces(globalOptions.profile) : listCachedCliWorkspaces(globalOptions.profile), globalOptions);
 		} catch (error) {
 			captureCliException(error);
@@ -29137,6 +29445,7 @@ function createProgram(programOptions = {}) {
 	});
 	workspaceCommand.command("switch").description("Set the active workspace ID used for Toggl 2.0 API calls").argument("[workspace-id]", "Workspace ID to activate (omit to choose interactively)").action(async (workspaceIdArg) => {
 		try {
+			if (isApiTokenMode()) throw new Error(CLI_API_TOKEN_WORKSPACE_MESSAGE);
 			const globalOptions = program.opts();
 			const target = switchCliWorkspace(await resolveWorkspaceIdOptional(workspaceIdArg, globalOptions, globalOptions.profile, {
 				isTty,
@@ -29156,8 +29465,14 @@ function createProgram(programOptions = {}) {
 		}
 	});
 	const profileCommand = program.command("profile").description("List, inspect, switch, or remove saved CLI profiles");
-	profileCommand.command("list").alias("ls").description("Show saved CLI profiles across environments").action(() => {
+	profileCommand.command("list").alias("ls").description("Show saved CLI profiles across environments").action(async () => {
 		try {
+			if (isApiTokenMode()) {
+				const identity = await apiToken.identity(program.opts());
+				process.stderr.write(`${CLI_API_TOKEN_PROFILES_MESSAGE}\n`);
+				output([describeCliApiTokenIdentity(identity)], program.opts());
+				return;
+			}
 			output(listCliProfiles(), program.opts());
 		} catch (error) {
 			captureCliException(error);
@@ -29165,8 +29480,12 @@ function createProgram(programOptions = {}) {
 			process.exitCode = 1;
 		}
 	});
-	profileCommand.command("current").description("Show the active CLI profile").action(() => {
+	profileCommand.command("current").description("Show the active CLI profile").action(async () => {
 		try {
+			if (isApiTokenMode()) {
+				output(describeCliApiTokenIdentity(await apiToken.identity(program.opts())), program.opts());
+				return;
+			}
 			output(getCurrentCliProfile(), program.opts());
 		} catch (error) {
 			captureCliException(error);
@@ -29176,6 +29495,7 @@ function createProgram(programOptions = {}) {
 	});
 	profileCommand.command("switch").description("Set the active CLI profile").argument("[profile]", "Profile name to activate (omit to choose interactively)").action(async (profileArg) => {
 		try {
+			if (isApiTokenMode()) throw new Error(CLI_API_TOKEN_PROFILES_MESSAGE);
 			const globalOptions = program.opts();
 			output(switchCliProfile(await resolveCliProfileNameOptional(profileArg, globalOptions, {
 				isTty,
@@ -29190,6 +29510,7 @@ function createProgram(programOptions = {}) {
 	});
 	profileCommand.command("remove").description("Remove a saved CLI profile").argument("[profile]", "Profile name to remove (omit to choose interactively)").action(async (profileArg) => {
 		try {
+			if (isApiTokenMode()) throw new Error(CLI_API_TOKEN_PROFILES_MESSAGE);
 			const globalOptions = program.opts();
 			output(removeCliProfile(await resolveCliProfileNameOptional(profileArg, globalOptions, {
 				isTty,
@@ -29249,6 +29570,7 @@ Common commands:
 		if (operationRequiresExplicitAcknowledgment(operation)) command.option("--yes", "Confirm destructive operation without prompting");
 		command.action(async (cmdOptions) => {
 			try {
+				assertOperationAvailableInAuthMode(operation);
 				const globalOptions = program.opts();
 				const explicitInput = hasExplicitInput(operation, cmdOptions);
 				const rawInput = await readInput(operation, cmdOptions);
@@ -29260,8 +29582,8 @@ Common commands:
 					isTty: isTty(),
 					env
 				});
-				const entityContext = willPrompt && !cmdOptions.dryRun ? { client: getClient(globalOptions) } : void 0;
-				await runOperation(operation, globalOptions, cmdOptions, willPrompt ? await promptForOperationInput(operation, rawInput, promptAdapter, entityContext) : rawInput);
+				const entityContext = willPrompt && !cmdOptions.dryRun ? { client: await getClient(globalOptions, apiToken) } : void 0;
+				await runOperation(operation, globalOptions, cmdOptions, apiToken, willPrompt ? await promptForOperationInput(operation, rawInput, promptAdapter, entityContext) : rawInput);
 			} catch (error) {
 				captureCliException(error);
 				process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
@@ -29292,4 +29614,4 @@ Common commands:
 //#endregion
 export { CommanderError as a, shutdownCliTelemetry as i, captureCliException as n, initCliTelemetry as r, createProgram as t };
 
-//# sourceMappingURL=program-BB9t7xvO.js.map
+//# sourceMappingURL=program-BLPqhZj7.js.map

package/build/{program-Bby4U_hT.d.ts → program-CxOdqdfD.d.ts}

@@ -978,5 +978,5 @@ interface CreateProgramOptions {
 }
 declare function createProgram(programOptions?: CreateProgramOptions): Command;
 //#endregion
-export { createProgram as t };
-//# sourceMappingURL=program-Bby4U_hT.d.ts.map
+export { createProgram as n, CreateProgramOptions as t };
+//# sourceMappingURL=program-CxOdqdfD.d.ts.map

package/build/program.d.ts

@@ -1,2 +1,2 @@
-import { t as createProgram } from "./program-Bby4U_hT.js";
-export { createProgram };
+import { n as createProgram, t as CreateProgramOptions } from "./program-CxOdqdfD.js";
+export { CreateProgramOptions, createProgram };

package/build/program.js

@@ -1,2 +1,2 @@
-import { t as createProgram } from "./program-BB9t7xvO.js";
+import { t as createProgram } from "./program-BLPqhZj7.js";
 export { createProgram };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@togglhq/cli",
-  "version": "1.11.226",
+  "version": "1.12.0",
   "description": "Toggl CLI for Toggl 2.0 API operations.",
   "license": "UNLICENSED",
   "type": "module",