@fragment-dev/cli 2026.6.30 → 2026.7.1-10

package/README.md

@@ -6,6 +6,7 @@
 
 <!-- commands -->
 * [`fragment add-ledger-entry`](#fragment-add-ledger-entry)
+* [`fragment api-client create`](#fragment-api-client-create)
 * [`fragment autocomplete [SHELL]`](#fragment-autocomplete-shell)
 * [`fragment commands`](#fragment-commands)
 * [`fragment create-custom-link`](#fragment-create-custom-link)
@@ -65,6 +66,39 @@ FLAG DESCRIPTIONS
     You may specify multiple parameters by repeating the flag.
 ```
 
+## `fragment api-client create`
+
+Create an API client for an integration.
+
+```
+USAGE
+  $ fragment api-client create --workspace <value> --name <value> [--role admin|reader] [--mcp-url <value>] [--output
+    <value>] [--format json|env]
+
+FLAGS
+  --format=<option>    [default: json] Output format (applies to both stdout and --output).
+                       <options: json|env>
+  --mcp-url=<value>    The Workspace MCP server origin (ex: https://mcp.us-west-2.fragment.dev). Falls back to
+                       FRAGMENT_MCP_URL.
+  --name=<value>       (required) A display name for the API client.
+  --output=<value>     Write the credentials to this file instead of stdout.
+  --role=<option>      Role to assign the API client (defaults to your own role, capped at it).
+                       <options: admin|reader>
+  --workspace=<value>  (required) The Workspace id to create the API client in.
+
+DESCRIPTION
+  Create an API client for an integration.
+
+  Authenticates in the browser and provisions a new API client for the
+  given Workspace, then writes the credentials to a file or stdout. The
+  authorizing user must have permission to create API clients.
+
+EXAMPLES
+  $ fragment api-client create --workspace <workspace-id> --name "Billing service" --role reader
+
+  $ fragment api-client create --workspace <workspace-id> --name CI --output ./fragment-client.json
+```
+
 ## `fragment autocomplete [SHELL]`
 
 Display autocomplete installation instructions.
@@ -342,17 +376,21 @@ Authenticate with FRAGMENT.
 
 ```
 USAGE
-  $ fragment login [--client-id <value>] [--client-secret <value>] [--api-url <value>] [--oauth-url
-    <value>] [--oauth-scope <value>] [--test]
+  $ fragment login [--browser] [--workspace <value>] [--mcp-url <value>] [--client-id <value>]
+    [--client-secret <value>] [--api-url <value>] [--oauth-url <value>] [--oauth-scope <value>] [--test]
 
 FLAGS
   --api-url=<value>        The API URL for your FRAGMENT Workspace (ex: https://api.us-west-2.fragment.dev/graphql)
+  --browser                Authenticate in the browser and provision an API client automatically.
   --client-id=<value>      The API Client ID for your FRAGMENT Workspace.
   --client-secret=<value>  The API Client Secret for your FRAGMENT Workspace
+  --mcp-url=<value>        The Workspace MCP server origin (ex: https://mcp.us-west-2.fragment.dev). Used with
+                           --browser.
   --oauth-scope=<value>    The OAuth Scope for your auth token (ex: https://api.us-west-2.fragment.dev/*)
   --oauth-url=<value>      The OAuth URL from which to retrieve your auth token (ex:
                            https://auth.fragment.dev/oauth2/token)
   --test                   If set, tests stored credentials only
+  --workspace=<value>      The Workspace id to authenticate against (required with --browser).
 
 DESCRIPTION
   Authenticate with FRAGMENT.
@@ -365,6 +403,8 @@ DESCRIPTION
 EXAMPLES
   $ fragment login
 
+  $ fragment login --browser --workspace <workspace-id>
+
   $ fragment login --client-id <client-id> --client-secret <client-secret> --api-url <api-url> --oauth-url <oauth-url>
 ```
 

package/dist/{chunk-I5JFFWZM.js → chunk-2VYJABNZ.js}

@@ -1,9 +1,9 @@
 import {
   AuthenticatedCommand
-} from "./chunk-Q25QYAZ7.js";
+} from "./chunk-FELYEHSZ.js";
 import {
   require_lib
-} from "./chunk-TRYLEOKB.js";
+} from "./chunk-PILLZB3E.js";
 import {
   require_source
 } from "./chunk-XK2D2Z44.js";

package/dist/{chunk-BBZDU3B4.js → chunk-34NLRFFT.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-L7ZGDLYU.js";
 import {
   FRAGMENT_VERSION_PATH
-} from "./chunk-WS2PJBP6.js";
+} from "./chunk-TLM4VKIC.js";
 import {
   init_cjs_shims
 } from "./chunk-7GH3YGSC.js";

package/dist/chunk-3SJL7FRS.js

@@ -0,0 +1,186 @@
+import {
+  init_cjs_shims
+} from "./chunk-7GH3YGSC.js";
+
+// src/lib/browserAuth.ts
+init_cjs_shims();
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+var AUTH_TIMEOUT_MS = 5 * 60 * 1e3;
+var CLI_BOOTSTRAP_CLIENT_NAME = "Fragment CLI";
+var defaultBrowserAuthDeps = (log) => ({
+  fetchFn: fetch,
+  openBrowser: async (url) => {
+    const open = (await import("./open-SJMVVA3H.js")).default;
+    return open(url);
+  },
+  startLoopback: startLoopbackServer,
+  log
+});
+var pkcePair = () => {
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+};
+var trimSlash = (url) => url.replace(/\/$/, "");
+var mcpResourceUrl = (mcpBaseUrl, workspaceId) => `${trimSlash(mcpBaseUrl)}/mcp/w/${encodeURIComponent(workspaceId)}`;
+var protectedResourceMetadataUrl = (mcpBaseUrl, workspaceId) => `${trimSlash(
+  mcpBaseUrl
+)}/.well-known/oauth-protected-resource/mcp/w/${encodeURIComponent(
+  workspaceId
+)}`;
+var jsonOk = async (response, what) => {
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(`${what} failed (${response.status}): ${body}`);
+  }
+  return response.json();
+};
+var errorPage = (message) => `<html><body>${message} You can close this window and return to the CLI.</body></html>`;
+var startLoopbackServer = (expectedState) => new Promise((resolveServer) => {
+  let resolveCode;
+  let rejectCode;
+  const codePromise = new Promise((res, rej) => {
+    resolveCode = res;
+    rejectCode = rej;
+  });
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (url.pathname !== "/callback") {
+      res.writeHead(404).end("Not found");
+      return;
+    }
+    const state = url.searchParams.get("state") ?? "";
+    if (state !== expectedState) {
+      res.writeHead(400, { "Content-Type": "text/html" }).end(errorPage("Invalid authorization state."));
+      return;
+    }
+    const error = url.searchParams.get("error");
+    const code = url.searchParams.get("code");
+    if (error) {
+      res.writeHead(400, { "Content-Type": "text/html" }).end(errorPage("Authorization was denied."));
+      rejectCode(new Error(`authorization denied: ${error}`));
+      return;
+    }
+    if (!code) {
+      res.writeHead(400, { "Content-Type": "text/html" }).end(errorPage("Authorization response was missing a code."));
+      rejectCode(new Error("callback missing code"));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "text/html" }).end(errorPage("Authorized."));
+    resolveCode(code);
+  });
+  server.listen(0, "127.0.0.1", () => {
+    const { port } = server.address();
+    resolveServer({
+      redirectUri: `http://127.0.0.1:${port}/callback`,
+      waitForCode: () => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          server.close();
+          reject(new Error("timed out waiting for browser authorization"));
+        }, AUTH_TIMEOUT_MS);
+        codePromise.then(
+          (code) => {
+            clearTimeout(timer);
+            resolve(code);
+          },
+          (err) => {
+            clearTimeout(timer);
+            reject(err);
+          }
+        );
+      }),
+      close: () => server.close()
+    });
+  });
+});
+var provisionApiClient = async ({ mcpBaseUrl, workspaceId, clientName, role }, deps) => {
+  const { fetchFn, openBrowser, startLoopback, log } = deps;
+  const resourceMetadata = await jsonOk(
+    await fetchFn(protectedResourceMetadataUrl(mcpBaseUrl, workspaceId)),
+    "discovering authorization server"
+  );
+  const issuer = resourceMetadata.authorization_servers?.[0];
+  if (!issuer) {
+    throw new Error("no authorization server advertised for this workspace");
+  }
+  const metadata = await jsonOk(
+    await fetchFn(
+      `${trimSlash(issuer)}/.well-known/oauth-authorization-server`
+    ),
+    "fetching issuer metadata"
+  );
+  if (!metadata.registration_endpoint) {
+    throw new Error("issuer does not support dynamic client registration");
+  }
+  const { verifier, challenge } = pkcePair();
+  const state = randomBytes(16).toString("base64url");
+  const loopback = await startLoopback(state);
+  try {
+    const registration = await jsonOk(
+      await fetchFn(metadata.registration_endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          redirect_uris: [loopback.redirectUri],
+          client_name: CLI_BOOTSTRAP_CLIENT_NAME
+        })
+      }),
+      "registering client"
+    );
+    const authorizeUrl = new URL(`${trimSlash(issuer)}/authorize`);
+    authorizeUrl.search = new URLSearchParams({
+      response_type: "code",
+      client_id: registration.client_id,
+      redirect_uri: loopback.redirectUri,
+      state,
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      resource: mcpResourceUrl(mcpBaseUrl, workspaceId),
+      intent: "api_client"
+    }).toString();
+    log(
+      `Opening your browser to authorize. If it doesn't open, visit:
+${authorizeUrl.toString()}`
+    );
+    await openBrowser(authorizeUrl.toString());
+    const code = await loopback.waitForCode();
+    const token = await jsonOk(
+      await fetchFn(metadata.token_endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          code,
+          redirect_uri: loopback.redirectUri,
+          client_id: registration.client_id,
+          code_verifier: verifier
+        })
+      }),
+      "exchanging authorization code"
+    );
+    const authHeader = { Authorization: `Bearer ${token.access_token}` };
+    const credentials = await jsonOk(
+      await fetchFn(`${trimSlash(mcpBaseUrl)}/api-clients`, {
+        method: "POST",
+        headers: { ...authHeader, "Content-Type": "application/json" },
+        body: JSON.stringify({ name: clientName, ...role ? { role } : {} })
+      }),
+      "creating API client"
+    );
+    await fetchFn(`${trimSlash(mcpBaseUrl)}/mcp-clients/self`, {
+      method: "DELETE",
+      headers: authHeader
+    }).catch(() => void 0);
+    return credentials;
+  } finally {
+    loopback.close();
+  }
+};
+
+export {
+  AUTH_TIMEOUT_MS,
+  defaultBrowserAuthDeps,
+  startLoopbackServer,
+  provisionApiClient
+};

package/dist/chunk-45CYJ3K6.js

@@ -0,0 +1,108 @@
+import {
+  defaultBrowserAuthDeps,
+  provisionApiClient
+} from "./chunk-3SJL7FRS.js";
+import {
+  FragmentCommand,
+  require_lib
+} from "./chunk-PILLZB3E.js";
+import {
+  resolveMcpBaseUrl
+} from "./chunk-TLM4VKIC.js";
+import {
+  __toESM,
+  init_cjs_shims
+} from "./chunk-7GH3YGSC.js";
+
+// src/commands/api-client/create.ts
+init_cjs_shims();
+var import_core = __toESM(require_lib(), 1);
+import { writeFile } from "node:fs/promises";
+var ROLE_KEYS = {
+  admin: "workspace_admin",
+  reader: "workspace_reader"
+};
+var ApiClientCreate = class _ApiClientCreate extends FragmentCommand {
+  static {
+    this.summary = "Create an API client for an integration.";
+  }
+  static {
+    this.description = `Authenticates in the browser and provisions a new API client for the
+  given Workspace, then writes the credentials to a file or stdout. The
+  authorizing user must have permission to create API clients.`;
+  }
+  static {
+    this.examples = [
+      '<%= config.bin %> <%= command.id %> --workspace <workspace-id> --name "Billing service" --role reader',
+      "<%= config.bin %> <%= command.id %> --workspace <workspace-id> --name CI --output ./fragment-client.json"
+    ];
+  }
+  static {
+    this.flags = {
+      workspace: import_core.Flags.string({
+        required: true,
+        description: "The Workspace id to create the API client in."
+      }),
+      name: import_core.Flags.string({
+        required: true,
+        description: "A display name for the API client."
+      }),
+      role: import_core.Flags.string({
+        required: false,
+        options: ["admin", "reader"],
+        description: "Role to assign the API client (defaults to your own role, capped at it)."
+      }),
+      "mcp-url": import_core.Flags.string({
+        required: false,
+        description: "The Workspace MCP server origin (ex: https://mcp.us-west-2.fragment.dev). Falls back to FRAGMENT_MCP_URL."
+      }),
+      output: import_core.Flags.string({
+        required: false,
+        description: "Write the credentials to this file instead of stdout."
+      }),
+      format: import_core.Flags.string({
+        required: false,
+        options: ["json", "env"],
+        default: "json",
+        description: "Output format (applies to both stdout and --output)."
+      })
+    };
+  }
+  render(result, format) {
+    return format === "env" ? [
+      `FRAGMENT_CLIENT_ID=${result.clientId}`,
+      `FRAGMENT_CLIENT_SECRET=${result.clientSecret}`,
+      `FRAGMENT_API_URL=${result.apiUrl}`,
+      `FRAGMENT_OAUTH_URL=${result.oauthUrl}`,
+      `FRAGMENT_OAUTH_SCOPE=${result.oauthScope}`
+    ].join("\n") : JSON.stringify(result, null, 2);
+  }
+  async run() {
+    const { flags } = await this.parse(_ApiClientCreate);
+    const mcpBaseUrl = resolveMcpBaseUrl(flags["mcp-url"]);
+    this.assert(mcpBaseUrl, {
+      message: "Must provide --mcp-url (or set FRAGMENT_MCP_URL), e.g. https://mcp.us-west-2.fragment.dev"
+    });
+    const result = await provisionApiClient(
+      {
+        mcpBaseUrl,
+        workspaceId: flags.workspace,
+        clientName: flags.name,
+        role: flags.role ? ROLE_KEYS[flags.role] : void 0
+      },
+      defaultBrowserAuthDeps((msg) => this.log(msg))
+    );
+    const rendered = this.render(result, flags.format);
+    if (flags.output) {
+      await writeFile(flags.output, `${rendered}
+`, { mode: 384 });
+      this.log(`API client credentials written to ${flags.output}`);
+      return;
+    }
+    this.log(rendered);
+  }
+};
+
+export {
+  ApiClientCreate
+};

package/dist/{chunk-UMAUSCLS.js → chunk-5A52AXRT.js}

@@ -1,12 +1,12 @@
 import {
   inquirer_default
-} from "./chunk-IJBNTQ7H.js";
+} from "./chunk-QJOWCJUB.js";
 import {
   AuthenticatedCommand
-} from "./chunk-Q25QYAZ7.js";
+} from "./chunk-FELYEHSZ.js";
 import {
   require_lib
-} from "./chunk-TRYLEOKB.js";
+} from "./chunk-PILLZB3E.js";
 import {
   require_source
 } from "./chunk-XK2D2Z44.js";

package/dist/{chunk-LNYDUY5F.js → chunk-5HH4NNSE.js}

@@ -1,9 +1,9 @@
 import {
   AuthenticatedCommand
-} from "./chunk-Q25QYAZ7.js";
+} from "./chunk-FELYEHSZ.js";
 import {
   require_lib
-} from "./chunk-TRYLEOKB.js";
+} from "./chunk-PILLZB3E.js";
 import {
   require_source
 } from "./chunk-XK2D2Z44.js";

package/dist/{chunk-ECSXGVPP.js → chunk-C7ROAUIM.js}

@@ -1,6 +1,6 @@
 import {
   AuthenticatedCommand
-} from "./chunk-Q25QYAZ7.js";
+} from "./chunk-FELYEHSZ.js";
 import {
   require_source
 } from "./chunk-XK2D2Z44.js";

package/dist/{chunk-Q25QYAZ7.js → chunk-FELYEHSZ.js}

@@ -5,7 +5,7 @@ import {
   FragmentCommand,
   GraphQLClient,
   require_lib
-} from "./chunk-TRYLEOKB.js";
+} from "./chunk-PILLZB3E.js";
 import {
   colorizeJson
 } from "./chunk-O7AE4SQS.js";

package/dist/{chunk-PFGF27Z7.js → chunk-GO2D2LDM.js}

@@ -5,7 +5,7 @@ import {
   getStructuralPath,
   getStructuralSubpaths,
   getSubpaths
-} from "./chunk-F4X6QF3A.js";
+} from "./chunk-V32GIUJT.js";
 import {
   BadRequestError,
   CurrencyMatchInputSchema,
@@ -21,7 +21,7 @@ import {
   currencyCodes,
   safe,
   z
-} from "./chunk-JN7B4RNC.js";
+} from "./chunk-VFXM2XYO.js";
 import {
   __commonJS,
   __toESM,

package/dist/{chunk-6BF2IGEK.js → chunk-HCTAYKGL.js}

@@ -1,9 +1,9 @@
 import {
   AuthenticatedCommand
-} from "./chunk-Q25QYAZ7.js";
+} from "./chunk-FELYEHSZ.js";
 import {
   require_lib
-} from "./chunk-TRYLEOKB.js";
+} from "./chunk-PILLZB3E.js";
 import {
   require_source
 } from "./chunk-XK2D2Z44.js";

package/dist/{chunk-VKFC45KB.js → chunk-J6GQWO4E.js}

@@ -1,9 +1,9 @@
 import {
   AuthenticatedCommand
-} from "./chunk-Q25QYAZ7.js";
+} from "./chunk-FELYEHSZ.js";
 import {
   require_lib
-} from "./chunk-TRYLEOKB.js";
+} from "./chunk-PILLZB3E.js";
 import {
   require_source
 } from "./chunk-XK2D2Z44.js";

package/dist/{chunk-T5GGVB7Q.js → chunk-JE5UVURV.js}

@@ -1,72 +1,75 @@
+import {
+  Workspace
+} from "./chunk-NWPJRN3W.js";
+import {
+  QuerySchemas
+} from "./chunk-UOXPSGVC.js";
 import {
   ReverseLedgerEntry
-} from "./chunk-NTVQKBTC.js";
+} from "./chunk-ZMSR4Z3E.js";
 import {
   Start
-} from "./chunk-A43XU7QS.js";
+} from "./chunk-LB3C4WTL.js";
 import {
   StoreSchema
-} from "./chunk-L3XNEX33.js";
+} from "./chunk-OZQUYOQH.js";
 import {
   Token
-} from "./chunk-ECSXGVPP.js";
+} from "./chunk-C7ROAUIM.js";
 import {
   UpdateLedgerAccount
-} from "./chunk-I5JFFWZM.js";
+} from "./chunk-2VYJABNZ.js";
 import {
   Update
-} from "./chunk-G5N2UVKQ.js";
+} from "./chunk-UMIUGX6O.js";
 import {
   VerifySchema
-} from "./chunk-UGKG4UKY.js";
+} from "./chunk-Y665FSTC.js";
 import {
-  Workspace
-} from "./chunk-PCAB73GF.js";
+  GenGraphQL
+} from "./chunk-MMEBN7SR.js";
 import {
   GetSchema
-} from "./chunk-UMAUSCLS.js";
+} from "./chunk-5A52AXRT.js";
 import {
   Init
-} from "./chunk-XKTOP23Z.js";
+} from "./chunk-SQL643PS.js";
 import {
   Login
-} from "./chunk-ESEZRPTU.js";
+} from "./chunk-NAJ7S3OV.js";
 import {
   MigrateLedgerEntry
-} from "./chunk-DTKNXMNB.js";
+} from "./chunk-XDGKUJ32.js";
 import {
   QueryLedgerAccounts
-} from "./chunk-BPA2ZDP4.js";
+} from "./chunk-MOZRABR6.js";
 import {
   QueryLedgers
-} from "./chunk-YKRLZ565.js";
+} from "./chunk-WMBVWK2M.js";
 import {
   GetSchema as GetSchema2
-} from "./chunk-OVTTESEV.js";
-import {
-  QuerySchemas
-} from "./chunk-3QZ3TI7I.js";
+} from "./chunk-VGBDSE7K.js";
 import {
   AddLedgerEntry
-} from "./chunk-VKFC45KB.js";
+} from "./chunk-J6GQWO4E.js";
+import {
+  ApiClientCreate
+} from "./chunk-45CYJ3K6.js";
 import {
   CreateCustomLink
-} from "./chunk-NM7ENVG2.js";
+} from "./chunk-QDA5BIHP.js";
 import {
   CreateLedger
-} from "./chunk-IO6HR226.js";
+} from "./chunk-QRP56DLY.js";
 import {
   DeleteCustomTxs
-} from "./chunk-GT4DQ3S5.js";
+} from "./chunk-VIVSBPCD.js";
 import {
   DeleteLedger
-} from "./chunk-6BF2IGEK.js";
+} from "./chunk-HCTAYKGL.js";
 import {
   DeleteSchema
-} from "./chunk-LNYDUY5F.js";
-import {
-  GenGraphQL
-} from "./chunk-CMB5L4GJ.js";
+} from "./chunk-5HH4NNSE.js";
 import {
   init_cjs_shims
 } from "./chunk-7GH3YGSC.js";
@@ -81,6 +84,7 @@ var COMMANDS = {
   // Auth commands
   login: Login,
   token: Token,
+  "api-client:create": ApiClientCreate,
   // Workspace commands
   workspace: Workspace,
   // Schema commands

package/dist/{chunk-A43XU7QS.js → chunk-LB3C4WTL.js}

@@ -1,7 +1,7 @@
 import {
   FragmentCommand,
   require_lib
-} from "./chunk-TRYLEOKB.js";
+} from "./chunk-PILLZB3E.js";
 import {
   require_source
 } from "./chunk-XK2D2Z44.js";

package/dist/{chunk-CMB5L4GJ.js → chunk-MMEBN7SR.js}

@@ -3,22 +3,22 @@ import {
   generateQueryFiles,
   schemaToEntryDefinitions,
   validateOutputName
-} from "./chunk-7X2QSWZ4.js";
+} from "./chunk-QPR6OBXW.js";
 import {
   Schema,
   parseWithError
-} from "./chunk-PFGF27Z7.js";
+} from "./chunk-GO2D2LDM.js";
 import {
   formatValidationErrors,
   logValidationErrors
-} from "./chunk-QI5VSJMP.js";
+} from "./chunk-PT6HAWJK.js";
 import {
   BadRequestError
-} from "./chunk-JN7B4RNC.js";
+} from "./chunk-VFXM2XYO.js";
 import {
   FragmentCommand,
   require_lib
-} from "./chunk-TRYLEOKB.js";
+} from "./chunk-PILLZB3E.js";
 import {
   getParsedSchema
 } from "./chunk-O7AE4SQS.js";

package/dist/{chunk-BPA2ZDP4.js → chunk-MOZRABR6.js}

@@ -1,9 +1,9 @@
 import {
   AuthenticatedCommand
-} from "./chunk-Q25QYAZ7.js";
+} from "./chunk-FELYEHSZ.js";
 import {
   require_lib
-} from "./chunk-TRYLEOKB.js";
+} from "./chunk-PILLZB3E.js";
 import {
   __toESM,
   init_cjs_shims