@backstage/cli-module-search 0.2.0-next.0 → 0.2.1-next.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @backstage/cli-module-search
 
+## 0.2.1-next.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/cli-node@0.3.6-next.0
+
+## 0.2.0
+
+### Minor Changes
+
+- 3d6721d: Add intent-based CLI modules for catalog, scaffolder, and search.
+
+  New modules provide domain-oriented subcommands that talk directly to the corresponding plugins' REST APIs:
+
+  - `@backstage/cli-module-catalog`: `catalog list`, `catalog get`, `catalog validate`, `catalog register`, `catalog unregister`
+  - `@backstage/cli-module-scaffolder`: `template list`, `template execute`, `template dry-run`
+  - `@backstage/cli-module-search`: `search`, `docs search`
+
+  The commands take their main input as a positional argument: an entity or template reference, a file path (or `-` for standard input) for `catalog validate` and `template dry-run`, a URL for `catalog register`, and the search terms for `search` and `docs search`. Repeatable `key=value` flags are used for filters, template values, and secrets, and comma-separated lists for `--fields`. Unknown flags are rejected.
+
+  The commands that list results, `catalog list`, `template list`, `search`, and `docs search`, support `--output human` (the default) or `--output json`, along with `--limit` and `--cursor` for paging. Each command prints a single page. Human output shows how many results were shown and, when more are available, prints the `--cursor` value to continue from. All other commands always print JSON. `catalog validate` checks every entity in a multi-document YAML file and prints a JSON array with one result per entity. `catalog validate` and `template dry-run` exit with a non-zero code when the input is invalid, while connection and authentication problems are reported as errors.
+
+  `@backstage/cli-node` now provides shared parsers for repeatable `key=value` inputs and comma-separated lists.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/cli-node@0.3.5
+  - @backstage/errors@1.3.2
+
 ## 0.2.0-next.0
 
 ### Minor Changes

package/dist/commands/docsSearch.cjs.js

@@ -8,73 +8,63 @@ var resolveAuth = require('../lib/resolveAuth.cjs.js');
 var intentFormat = require('../lib/intentFormat.cjs.js');
 
 var docsSearch = async ({ args, info }) => {
-  const nonFlagArgs = [];
-  const flagArgs = [];
-  let skipNext = false;
-  for (let i = 0; i < args.length; i++) {
-    if (skipNext) {
-      skipNext = false;
-      continue;
-    }
-    if (args[i].startsWith("-")) {
-      flagArgs.push(args[i]);
-      if (i + 1 < args.length && !args[i + 1].startsWith("-") && !args[i].includes("=")) {
-        flagArgs.push(args[i + 1]);
-        skipNext = true;
-      }
-    } else {
-      nonFlagArgs.push(args[i]);
-    }
-  }
-  const { flags } = cleye.cli(
+  const parsed = cleye.cli(
     {
       name: info.usage,
+      strictFlags: true,
+      parameters: ["<term...>"],
       flags: {
-        "page-limit": {
+        limit: {
           type: Number,
-          description: "Results per page (default: 10)"
-        },
-        "page-cursor": {
-          type: String,
-          description: "Pagination cursor"
+          description: "Maximum number of results to return per page"
         },
-        output: {
+        cursor: {
           type: String,
-          description: "Output format: human (default), json"
+          description: "Continue from the cursor returned by a previous page"
         },
-        instance: {
-          type: String,
-          description: "Name of the instance to use"
-        }
+        ...intentFormat.outputFlag,
+        ...resolveAuth.instanceFlag
       }
     },
     void 0,
-    flagArgs
+    args
   );
-  const term = nonFlagArgs.join(" ");
-  if (!term) {
-    throw new Error("Search term is required. Usage: docs search <term>");
-  }
+  const { flags } = parsed;
+  const term = parsed._.term.join(" ");
   const mode = intentFormat.parseOutputFlag(flags);
   const { accessToken, baseUrl } = await resolveAuth.resolveAuth(flags.instance);
   const client = new SearchClient.SearchClient(baseUrl, accessToken);
-  const response = await client.query({
-    term,
-    types: ["techdocs"],
-    pageLimit: flags["page-limit"],
-    pageCursor: flags["page-cursor"]
-  });
-  const result = {
-    results: response.results,
-    nextPageCursor: response.nextPageCursor,
-    totalItems: response.numberOfResults,
-    hasMoreResults: response.nextPageCursor !== void 0
+  const fetchPage = async (cursor) => {
+    const response = await client.query({
+      term,
+      types: ["techdocs"],
+      pageLimit: flags.limit,
+      pageCursor: cursor
+    });
+    return {
+      results: response.results,
+      nextPageCursor: response.nextPageCursor,
+      totalItems: response.numberOfResults,
+      hasMoreResults: response.nextPageCursor !== void 0
+    };
   };
   if (mode === "json") {
-    intentFormat.writeJson(result);
-  } else {
-    process.stdout.write(intentFormat.formatSearchResults(result.results));
+    intentFormat.writeJson(await fetchPage(flags.cursor));
+    return;
   }
+  await intentFormat.printPage(
+    async (cursor) => {
+      const page = await fetchPage(cursor);
+      return {
+        ...page,
+        count: page.results.length,
+        total: page.totalItems,
+        nextCursor: page.nextPageCursor
+      };
+    },
+    (page) => process.stdout.write(intentFormat.formatSearchResults(page.results)),
+    flags.cursor
+  );
 };
 
 exports.default = docsSearch;

package/dist/commands/docsSearch.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"docsSearch.cjs.js","sources":["../../src/commands/docsSearch.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { cli } from 'cleye';\nimport type { CliCommandContext } from '@backstage/cli-node';\nimport { SearchClient } from '../lib/SearchClient';\nimport { resolveAuth } from '../lib/resolveAuth';\nimport {\n  parseOutputFlag,\n  writeJson,\n  formatSearchResults,\n} from '../lib/intentFormat';\n\nexport default async ({ args, info }: CliCommandContext) => {\n  const nonFlagArgs: string[] = [];\n  const flagArgs: string[] = [];\n  let skipNext = false;\n\n  for (let i = 0; i < args.length; i++) {\n    if (skipNext) {\n      skipNext = false;\n      continue;\n    }\n    if (args[i].startsWith('-')) {\n      flagArgs.push(args[i]);\n      if (\n        i + 1 < args.length &&\n        !args[i + 1].startsWith('-') &&\n        !args[i].includes('=')\n      ) {\n        flagArgs.push(args[i + 1]);\n        skipNext = true;\n      }\n    } else {\n      nonFlagArgs.push(args[i]);\n    }\n  }\n\n  const { flags } = cli(\n    {\n      name: info.usage,\n      flags: {\n        'page-limit': {\n          type: Number,\n          description: 'Results per page (default: 10)',\n        },\n        'page-cursor': {\n          type: String,\n          description: 'Pagination cursor',\n        },\n        output: {\n          type: String,\n          description: 'Output format: human (default), json',\n        },\n        instance: {\n          type: String,\n          description: 'Name of the instance to use',\n        },\n      },\n    },\n    undefined,\n    flagArgs,\n  );\n\n  const term = nonFlagArgs.join(' ');\n  if (!term) {\n    throw new Error('Search term is required. Usage: docs search <term>');\n  }\n\n  const mode = parseOutputFlag(flags as Record<string, unknown>);\n  const { accessToken, baseUrl } = await resolveAuth(flags.instance);\n  const client = new SearchClient(baseUrl, accessToken);\n\n  const response = await client.query({\n    term,\n    types: ['techdocs'],\n    pageLimit: flags['page-limit'],\n    pageCursor: flags['page-cursor'],\n  });\n  const result = {\n    results: response.results,\n    nextPageCursor: response.nextPageCursor,\n    totalItems: response.numberOfResults,\n    hasMoreResults: response.nextPageCursor !== undefined,\n  };\n\n  if (mode === 'json') {\n    writeJson(result);\n  } else {\n    process.stdout.write(formatSearchResults(result.results));\n  }\n};\n"],"names":["cli","parseOutputFlag","resolveAuth","SearchClient","writeJson","formatSearchResults"],"mappings":"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"}
+{"version":3,"file":"docsSearch.cjs.js","sources":["../../src/commands/docsSearch.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { cli } from 'cleye';\nimport type { CliCommandContext } from '@backstage/cli-node';\nimport { SearchClient } from '../lib/SearchClient';\nimport { instanceFlag, resolveAuth } from '../lib/resolveAuth';\nimport {\n  outputFlag,\n  printPage,\n  parseOutputFlag,\n  writeJson,\n  formatSearchResults,\n} from '../lib/intentFormat';\n\nexport default async ({ args, info }: CliCommandContext) => {\n  const parsed = cli(\n    {\n      name: info.usage,\n      strictFlags: true,\n      parameters: ['<term...>'],\n      flags: {\n        limit: {\n          type: Number,\n          description: 'Maximum number of results to return per page',\n        },\n        cursor: {\n          type: String,\n          description: 'Continue from the cursor returned by a previous page',\n        },\n        ...outputFlag,\n        ...instanceFlag,\n      },\n    },\n    undefined,\n    args,\n  );\n  const { flags } = parsed;\n\n  const term = parsed._.term.join(' ');\n  const mode = parseOutputFlag(flags as Record<string, unknown>);\n\n  const { accessToken, baseUrl } = await resolveAuth(flags.instance);\n  const client = new SearchClient(baseUrl, accessToken);\n\n  const fetchPage = async (cursor?: string) => {\n    const response = await client.query({\n      term,\n      types: ['techdocs'],\n      pageLimit: flags.limit,\n      pageCursor: cursor,\n    });\n    return {\n      results: response.results,\n      nextPageCursor: response.nextPageCursor,\n      totalItems: response.numberOfResults,\n      hasMoreResults: response.nextPageCursor !== undefined,\n    };\n  };\n\n  if (mode === 'json') {\n    writeJson(await fetchPage(flags.cursor));\n    return;\n  }\n\n  await printPage(\n    async cursor => {\n      const page = await fetchPage(cursor);\n      return {\n        ...page,\n        count: page.results.length,\n        total: page.totalItems,\n        nextCursor: page.nextPageCursor,\n      };\n    },\n    page => process.stdout.write(formatSearchResults(page.results)),\n    flags.cursor,\n  );\n};\n"],"names":["cli","outputFlag","instanceFlag","parseOutputFlag","resolveAuth","SearchClient","writeJson","printPage","formatSearchResults"],"mappings":";;;;;;;;;AA4BA,iBAAe,OAAO,EAAE,IAAA,EAAM,IAAA,EAAK,KAAyB;AAC1D,EAAA,MAAM,MAAA,GAASA,SAAA;AAAA,IACb;AAAA,MACE,MAAM,IAAA,CAAK,KAAA;AAAA,MACX,WAAA,EAAa,IAAA;AAAA,MACb,UAAA,EAAY,CAAC,WAAW,CAAA;AAAA,MACxB,KAAA,EAAO;AAAA,QACL,KAAA,EAAO;AAAA,UACL,IAAA,EAAM,MAAA;AAAA,UACN,WAAA,EAAa;AAAA,SACf;AAAA,QACA,MAAA,EAAQ;AAAA,UACN,IAAA,EAAM,MAAA;AAAA,UACN,WAAA,EAAa;AAAA,SACf;AAAA,QACA,GAAGC,uBAAA;AAAA,QACH,GAAGC;AAAA;AACL,KACF;AAAA,IACA,MAAA;AAAA,IACA;AAAA,GACF;AACA,EAAA,MAAM,EAAE,OAAM,GAAI,MAAA;AAElB,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,CAAA,CAAE,IAAA,CAAK,KAAK,GAAG,CAAA;AACnC,EAAA,MAAM,IAAA,GAAOC,6BAAgB,KAAgC,CAAA;AAE7D,EAAA,MAAM,EAAE,WAAA,EAAa,OAAA,KAAY,MAAMC,uBAAA,CAAY,MAAM,QAAQ,CAAA;AACjE,EAAA,MAAM,MAAA,GAAS,IAAIC,yBAAA,CAAa,OAAA,EAAS,WAAW,CAAA;AAEpD,EAAA,MAAM,SAAA,GAAY,OAAO,MAAA,KAAoB;AAC3C,IAAA,MAAM,QAAA,GAAW,MAAM,MAAA,CAAO,KAAA,CAAM;AAAA,MAClC,IAAA;AAAA,MACA,KAAA,EAAO,CAAC,UAAU,CAAA;AAAA,MAClB,WAAW,KAAA,CAAM,KAAA;AAAA,MACjB,UAAA,EAAY;AAAA,KACb,CAAA;AACD,IAAA,OAAO;AAAA,MACL,SAAS,QAAA,CAAS,OAAA;AAAA,MAClB,gBAAgB,QAAA,CAAS,cAAA;AAAA,MACzB,YAAY,QAAA,CAAS,eAAA;AAAA,MACrB,cAAA,EAAgB,SAAS,cAAA,KAAmB;AAAA,KAC9C;AAAA,EACF,CAAA;AAEA,EAAA,IAAI,SAAS,MAAA,EAAQ;AACnB,IAAAC,sBAAA,CAAU,MAAM,SAAA,CAAU,KAAA,CAAM,MAAM,CAAC,CAAA;AACvC,IAAA;AAAA,EACF;AAEA,EAAA,MAAMC,sBAAA;AAAA,IACJ,OAAM,MAAA,KAAU;AACd,MAAA,MAAM,IAAA,GAAO,MAAM,SAAA,CAAU,MAAM,CAAA;AACnC,MAAA,OAAO;AAAA,QACL,GAAG,IAAA;AAAA,QACH,KAAA,EAAO,KAAK,OAAA,CAAQ,MAAA;AAAA,QACpB,OAAO,IAAA,CAAK,UAAA;AAAA,QACZ,YAAY,IAAA,CAAK;AAAA,OACnB;AAAA,IACF,CAAA;AAAA,IACA,UAAQ,OAAA,CAAQ,MAAA,CAAO,MAAMC,gCAAA,CAAoB,IAAA,CAAK,OAAO,CAAC,CAAA;AAAA,IAC9D,KAAA,CAAM;AAAA,GACR;AACF,CAAA;;"}

package/dist/commands/search.cjs.js

@@ -9,86 +9,76 @@ var resolveAuth = require('../lib/resolveAuth.cjs.js');
 var intentFormat = require('../lib/intentFormat.cjs.js');
 
 var search = async ({ args, info }) => {
-  const nonFlagArgs = [];
-  let skipNext = false;
-  for (let i = 0; i < args.length; i++) {
-    if (skipNext) {
-      skipNext = false;
-      continue;
-    }
-    if (args[i].startsWith("-")) {
-      if (i + 1 < args.length && !args[i + 1].startsWith("-") && !args[i].includes("=")) {
-        skipNext = true;
-      }
-    } else {
-      nonFlagArgs.push(args[i]);
-    }
-  }
   const parsed = cleye.cli(
     {
       name: info.usage,
       strictFlags: true,
       parameters: ["<term...>"],
       flags: {
-        types: {
-          type: String,
-          description: "Comma-separated document types"
+        type: {
+          type: [String],
+          description: "Only search documents of this type, for example techdocs (repeatable)",
+          default: []
         },
         filter: {
           type: [String],
-          description: "Query filter as repeatable key=value input",
+          description: "Filter results by a field, as key=value (repeatable)",
           default: []
         },
-        "page-limit": {
+        limit: {
           type: Number,
-          description: "Results per page (default: 10)"
+          description: "Maximum number of results to return per page"
         },
-        "page-cursor": {
+        cursor: {
           type: String,
-          description: "Pagination cursor"
+          description: "Continue from the cursor returned by a previous page"
         },
-        output: {
-          type: String,
-          description: "Output format: human (default), json"
-        },
-        instance: {
-          type: String,
-          description: "Name of the instance to use"
-        }
+        ...intentFormat.outputFlag,
+        ...resolveAuth.instanceFlag
       }
     },
     void 0,
     args
   );
   const { flags } = parsed;
-  const termParts = parsed._?.term ?? nonFlagArgs;
-  const term = termParts.join(" ");
-  if (!term) {
-    throw new Error(
-      "Search term is required. Usage: search <term> [--types techdocs]"
-    );
-  }
+  const term = parsed._.term.join(" ");
   const mode = intentFormat.parseOutputFlag(flags);
+  const types = flags.type.length > 0 ? flags.type : void 0;
+  const filters = cliNode.parseKeyValuePairs(flags.filter);
   const { accessToken, baseUrl } = await resolveAuth.resolveAuth(flags.instance);
   const client = new SearchClient.SearchClient(baseUrl, accessToken);
-  const response = await client.query({
-    term,
-    types: cliNode.parseCommaSeparatedList(flags.types),
-    filters: cliNode.parseKeyValuePairs(flags.filter),
-    pageLimit: flags["page-limit"],
-    pageCursor: flags["page-cursor"]
-  });
-  const result = {
-    results: response.results,
-    nextPageCursor: response.nextPageCursor,
-    totalItems: response.numberOfResults,
-    hasMoreResults: response.nextPageCursor !== void 0
+  const fetchPage = async (cursor) => {
+    const response = await client.query({
+      term,
+      types,
+      filters,
+      pageLimit: flags.limit,
+      pageCursor: cursor
+    });
+    return {
+      results: response.results,
+      nextPageCursor: response.nextPageCursor,
+      totalItems: response.numberOfResults,
+      hasMoreResults: response.nextPageCursor !== void 0
+    };
   };
   if (mode === "json") {
-    intentFormat.writeJson(result);
-  } else {
-    process.stdout.write(intentFormat.formatSearchResults(result.results));
+    intentFormat.writeJson(await fetchPage(flags.cursor));
+    return;
   }
+  await intentFormat.printPage(
+    async (cursor) => {
+      const page = await fetchPage(cursor);
+      return {
+        ...page,
+        count: page.results.length,
+        total: page.totalItems,
+        nextCursor: page.nextPageCursor
+      };
+    },
+    (page) => process.stdout.write(intentFormat.formatSearchResults(page.results)),
+    flags.cursor
+  );
 };
 
 exports.default = search;

package/dist/commands/search.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"search.cjs.js","sources":["../../src/commands/search.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { cli } from 'cleye';\nimport {\n  parseCommaSeparatedList,\n  parseKeyValuePairs,\n  type CliCommandContext,\n} from '@backstage/cli-node';\nimport { SearchClient } from '../lib/SearchClient';\nimport { resolveAuth } from '../lib/resolveAuth';\nimport {\n  parseOutputFlag,\n  writeJson,\n  formatSearchResults,\n} from '../lib/intentFormat';\n\nexport default async ({ args, info }: CliCommandContext) => {\n  const nonFlagArgs: string[] = [];\n  let skipNext = false;\n\n  for (let i = 0; i < args.length; i++) {\n    if (skipNext) {\n      skipNext = false;\n      continue;\n    }\n    if (args[i].startsWith('-')) {\n      if (\n        i + 1 < args.length &&\n        !args[i + 1].startsWith('-') &&\n        !args[i].includes('=')\n      ) {\n        skipNext = true;\n      }\n    } else {\n      nonFlagArgs.push(args[i]);\n    }\n  }\n\n  const parsed = cli(\n    {\n      name: info.usage,\n      strictFlags: true,\n      parameters: ['<term...>'],\n      flags: {\n        types: {\n          type: String,\n          description: 'Comma-separated document types',\n        },\n        filter: {\n          type: [String] as const,\n          description: 'Query filter as repeatable key=value input',\n          default: [] as string[],\n        },\n        'page-limit': {\n          type: Number,\n          description: 'Results per page (default: 10)',\n        },\n        'page-cursor': {\n          type: String,\n          description: 'Pagination cursor',\n        },\n        output: {\n          type: String,\n          description: 'Output format: human (default), json',\n        },\n        instance: {\n          type: String,\n          description: 'Name of the instance to use',\n        },\n      },\n    },\n    undefined,\n    args,\n  );\n  const { flags } = parsed;\n\n  const termParts = parsed._?.term ?? nonFlagArgs;\n  const term = termParts.join(' ');\n  if (!term) {\n    throw new Error(\n      'Search term is required. Usage: search <term> [--types techdocs]',\n    );\n  }\n\n  const mode = parseOutputFlag(flags as Record<string, unknown>);\n  const { accessToken, baseUrl } = await resolveAuth(flags.instance);\n  const client = new SearchClient(baseUrl, accessToken);\n\n  const response = await client.query({\n    term,\n    types: parseCommaSeparatedList(flags.types),\n    filters: parseKeyValuePairs(flags.filter),\n    pageLimit: flags['page-limit'],\n    pageCursor: flags['page-cursor'],\n  });\n  const result = {\n    results: response.results,\n    nextPageCursor: response.nextPageCursor,\n    totalItems: response.numberOfResults,\n    hasMoreResults: response.nextPageCursor !== undefined,\n  };\n\n  if (mode === 'json') {\n    writeJson(result);\n  } else {\n    process.stdout.write(formatSearchResults(result.results));\n  }\n};\n"],"names":["cli","parseOutputFlag","resolveAuth","SearchClient","parseCommaSeparatedList","parseKeyValuePairs","writeJson","formatSearchResults"],"mappings":"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"}
+{"version":3,"file":"search.cjs.js","sources":["../../src/commands/search.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { cli } from 'cleye';\nimport {\n  parseKeyValuePairs,\n  type CliCommandContext,\n} from '@backstage/cli-node';\nimport { SearchClient } from '../lib/SearchClient';\nimport { instanceFlag, resolveAuth } from '../lib/resolveAuth';\nimport {\n  outputFlag,\n  printPage,\n  parseOutputFlag,\n  writeJson,\n  formatSearchResults,\n} from '../lib/intentFormat';\n\nexport default async ({ args, info }: CliCommandContext) => {\n  const parsed = cli(\n    {\n      name: info.usage,\n      strictFlags: true,\n      parameters: ['<term...>'],\n      flags: {\n        type: {\n          type: [String] as const,\n          description:\n            'Only search documents of this type, for example techdocs (repeatable)',\n          default: [] as string[],\n        },\n        filter: {\n          type: [String] as const,\n          description: 'Filter results by a field, as key=value (repeatable)',\n          default: [] as string[],\n        },\n        limit: {\n          type: Number,\n          description: 'Maximum number of results to return per page',\n        },\n        cursor: {\n          type: String,\n          description: 'Continue from the cursor returned by a previous page',\n        },\n        ...outputFlag,\n        ...instanceFlag,\n      },\n    },\n    undefined,\n    args,\n  );\n  const { flags } = parsed;\n\n  const term = parsed._.term.join(' ');\n  const mode = parseOutputFlag(flags as Record<string, unknown>);\n  const types = flags.type.length > 0 ? flags.type : undefined;\n  const filters = parseKeyValuePairs(flags.filter);\n\n  const { accessToken, baseUrl } = await resolveAuth(flags.instance);\n  const client = new SearchClient(baseUrl, accessToken);\n\n  const fetchPage = async (cursor?: string) => {\n    const response = await client.query({\n      term,\n      types,\n      filters,\n      pageLimit: flags.limit,\n      pageCursor: cursor,\n    });\n    return {\n      results: response.results,\n      nextPageCursor: response.nextPageCursor,\n      totalItems: response.numberOfResults,\n      hasMoreResults: response.nextPageCursor !== undefined,\n    };\n  };\n\n  if (mode === 'json') {\n    writeJson(await fetchPage(flags.cursor));\n    return;\n  }\n\n  await printPage(\n    async cursor => {\n      const page = await fetchPage(cursor);\n      return {\n        ...page,\n        count: page.results.length,\n        total: page.totalItems,\n        nextCursor: page.nextPageCursor,\n      };\n    },\n    page => process.stdout.write(formatSearchResults(page.results)),\n    flags.cursor,\n  );\n};\n"],"names":["cli","outputFlag","instanceFlag","parseOutputFlag","parseKeyValuePairs","resolveAuth","SearchClient","writeJson","printPage","formatSearchResults"],"mappings":";;;;;;;;;;AA+BA,aAAe,OAAO,EAAE,IAAA,EAAM,IAAA,EAAK,KAAyB;AAC1D,EAAA,MAAM,MAAA,GAASA,SAAA;AAAA,IACb;AAAA,MACE,MAAM,IAAA,CAAK,KAAA;AAAA,MACX,WAAA,EAAa,IAAA;AAAA,MACb,UAAA,EAAY,CAAC,WAAW,CAAA;AAAA,MACxB,KAAA,EAAO;AAAA,QACL,IAAA,EAAM;AAAA,UACJ,IAAA,EAAM,CAAC,MAAM,CAAA;AAAA,UACb,WAAA,EACE,uEAAA;AAAA,UACF,SAAS;AAAC,SACZ;AAAA,QACA,MAAA,EAAQ;AAAA,UACN,IAAA,EAAM,CAAC,MAAM,CAAA;AAAA,UACb,WAAA,EAAa,sDAAA;AAAA,UACb,SAAS;AAAC,SACZ;AAAA,QACA,KAAA,EAAO;AAAA,UACL,IAAA,EAAM,MAAA;AAAA,UACN,WAAA,EAAa;AAAA,SACf;AAAA,QACA,MAAA,EAAQ;AAAA,UACN,IAAA,EAAM,MAAA;AAAA,UACN,WAAA,EAAa;AAAA,SACf;AAAA,QACA,GAAGC,uBAAA;AAAA,QACH,GAAGC;AAAA;AACL,KACF;AAAA,IACA,MAAA;AAAA,IACA;AAAA,GACF;AACA,EAAA,MAAM,EAAE,OAAM,GAAI,MAAA;AAElB,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,CAAA,CAAE,IAAA,CAAK,KAAK,GAAG,CAAA;AACnC,EAAA,MAAM,IAAA,GAAOC,6BAAgB,KAAgC,CAAA;AAC7D,EAAA,MAAM,QAAQ,KAAA,CAAM,IAAA,CAAK,MAAA,GAAS,CAAA,GAAI,MAAM,IAAA,GAAO,MAAA;AACnD,EAAA,MAAM,OAAA,GAAUC,0BAAA,CAAmB,KAAA,CAAM,MAAM,CAAA;AAE/C,EAAA,MAAM,EAAE,WAAA,EAAa,OAAA,KAAY,MAAMC,uBAAA,CAAY,MAAM,QAAQ,CAAA;AACjE,EAAA,MAAM,MAAA,GAAS,IAAIC,yBAAA,CAAa,OAAA,EAAS,WAAW,CAAA;AAEpD,EAAA,MAAM,SAAA,GAAY,OAAO,MAAA,KAAoB;AAC3C,IAAA,MAAM,QAAA,GAAW,MAAM,MAAA,CAAO,KAAA,CAAM;AAAA,MAClC,IAAA;AAAA,MACA,KAAA;AAAA,MACA,OAAA;AAAA,MACA,WAAW,KAAA,CAAM,KAAA;AAAA,MACjB,UAAA,EAAY;AAAA,KACb,CAAA;AACD,IAAA,OAAO;AAAA,MACL,SAAS,QAAA,CAAS,OAAA;AAAA,MAClB,gBAAgB,QAAA,CAAS,cAAA;AAAA,MACzB,YAAY,QAAA,CAAS,eAAA;AAAA,MACrB,cAAA,EAAgB,SAAS,cAAA,KAAmB;AAAA,KAC9C;AAAA,EACF,CAAA;AAEA,EAAA,IAAI,SAAS,MAAA,EAAQ;AACnB,IAAAC,sBAAA,CAAU,MAAM,SAAA,CAAU,KAAA,CAAM,MAAM,CAAC,CAAA;AACvC,IAAA;AAAA,EACF;AAEA,EAAA,MAAMC,sBAAA;AAAA,IACJ,OAAM,MAAA,KAAU;AACd,MAAA,MAAM,IAAA,GAAO,MAAM,SAAA,CAAU,MAAM,CAAA;AACnC,MAAA,OAAO;AAAA,QACL,GAAG,IAAA;AAAA,QACH,KAAA,EAAO,KAAK,OAAA,CAAQ,MAAA;AAAA,QACpB,OAAO,IAAA,CAAK,UAAA;AAAA,QACZ,YAAY,IAAA,CAAK;AAAA,OACnB;AAAA,IACF,CAAA;AAAA,IACA,UAAQ,OAAA,CAAQ,MAAA,CAAO,MAAMC,gCAAA,CAAoB,IAAA,CAAK,OAAO,CAAC,CAAA;AAAA,IAC9D,KAAA,CAAM;AAAA,GACR;AACF,CAAA;;"}

package/dist/lib/intentFormat.cjs.js

@@ -6,8 +6,36 @@ function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'defau
 
 var chalk__default = /*#__PURE__*/_interopDefaultCompat(chalk);
 
+const outputFlag = {
+  output: {
+    type: String,
+    description: 'Output format: "human" (default) or "json"'
+  }
+};
 function parseOutputFlag(flags) {
-  return flags.output === "json" ? "json" : "human";
+  const output = flags.output;
+  if (output === void 0 || output === "human") return "human";
+  if (output === "json") return "json";
+  throw new Error(
+    `Invalid --output value "${String(output)}", expected "human" or "json"`
+  );
+}
+async function printPage(fetchPage, render, cursor) {
+  const page = await fetchPage(cursor);
+  render(page);
+  if (page.count > 0) {
+    const total = page.total === void 0 ? "" : ` of ${page.total}`;
+    process.stdout.write(`${chalk__default.default.dim(`Showing ${page.count}${total}`)}
+`);
+  }
+  if (page.nextCursor) {
+    process.stdout.write(
+      `${chalk__default.default.dim(
+        `More results available, use --cursor ${page.nextCursor} to show them`
+      )}
+`
+    );
+  }
 }
 function writeJson(data) {
   process.stdout.write(`${JSON.stringify(data, null, 2)}
@@ -34,6 +62,8 @@ function formatSearchResults(results) {
 }
 
 exports.formatSearchResults = formatSearchResults;
+exports.outputFlag = outputFlag;
 exports.parseOutputFlag = parseOutputFlag;
+exports.printPage = printPage;
 exports.writeJson = writeJson;
 //# sourceMappingURL=intentFormat.cjs.js.map

package/dist/lib/intentFormat.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"intentFormat.cjs.js","sources":["../../src/lib/intentFormat.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport chalk from 'chalk';\n\nexport type OutputMode = 'human' | 'json';\n\nexport function parseOutputFlag(flags: Record<string, unknown>): OutputMode {\n  return flags.output === 'json' ? 'json' : 'human';\n}\n\nexport function writeJson(data: unknown): void {\n  process.stdout.write(`${JSON.stringify(data, null, 2)}\\n`);\n}\n\nexport function formatSearchResults(\n  results: Array<Record<string, unknown>>,\n): string {\n  if (results.length === 0) {\n    return `${chalk.yellow('No results found.')}\\n`;\n  }\n\n  const lines: string[] = [];\n  for (const result of results) {\n    const doc = result.document as Record<string, unknown> | undefined;\n    const title = String(doc?.title ?? result.title ?? '');\n    const location = String(doc?.location ?? result.location ?? '');\n    const text = String(doc?.text ?? result.text ?? '');\n    const snippet = text.length > 120 ? `${text.slice(0, 120)}...` : text;\n\n    lines.push(chalk.bold(title));\n    if (location) lines.push(`  ${chalk.dim(location)}`);\n    if (snippet) lines.push(`  ${snippet}`);\n    lines.push('');\n  }\n\n  return lines.join('\\n');\n}\n"],"names":["chalk"],"mappings":";;;;;;;;AAoBO,SAAS,gBAAgB,KAAA,EAA4C;AAC1E,EAAA,OAAO,KAAA,CAAM,MAAA,KAAW,MAAA,GAAS,MAAA,GAAS,OAAA;AAC5C;AAEO,SAAS,UAAU,IAAA,EAAqB;AAC7C,EAAA,OAAA,CAAQ,MAAA,CAAO,MAAM,CAAA,EAAG,IAAA,CAAK,UAAU,IAAA,EAAM,IAAA,EAAM,CAAC,CAAC;AAAA,CAAI,CAAA;AAC3D;AAEO,SAAS,oBACd,OAAA,EACQ;AACR,EAAA,IAAI,OAAA,CAAQ,WAAW,CAAA,EAAG;AACxB,IAAA,OAAO,CAAA,EAAGA,sBAAA,CAAM,MAAA,CAAO,mBAAmB,CAAC;AAAA,CAAA;AAAA,EAC7C;AAEA,EAAA,MAAM,QAAkB,EAAC;AACzB,EAAA,KAAA,MAAW,UAAU,OAAA,EAAS;AAC5B,IAAA,MAAM,MAAM,MAAA,CAAO,QAAA;AACnB,IAAA,MAAM,QAAQ,MAAA,CAAO,GAAA,EAAK,KAAA,IAAS,MAAA,CAAO,SAAS,EAAE,CAAA;AACrD,IAAA,MAAM,WAAW,MAAA,CAAO,GAAA,EAAK,QAAA,IAAY,MAAA,CAAO,YAAY,EAAE,CAAA;AAC9D,IAAA,MAAM,OAAO,MAAA,CAAO,GAAA,EAAK,IAAA,IAAQ,MAAA,CAAO,QAAQ,EAAE,CAAA;AAClD,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,MAAA,GAAS,GAAA,GAAM,CAAA,EAAG,KAAK,KAAA,CAAM,CAAA,EAAG,GAAG,CAAC,CAAA,GAAA,CAAA,GAAQ,IAAA;AAEjE,IAAA,KAAA,CAAM,IAAA,CAAKA,sBAAA,CAAM,IAAA,CAAK,KAAK,CAAC,CAAA;AAC5B,IAAA,IAAI,QAAA,QAAgB,IAAA,CAAK,CAAA,EAAA,EAAKA,uBAAM,GAAA,CAAI,QAAQ,CAAC,CAAA,CAAE,CAAA;AACnD,IAAA,IAAI,OAAA,EAAS,KAAA,CAAM,IAAA,CAAK,CAAA,EAAA,EAAK,OAAO,CAAA,CAAE,CAAA;AACtC,IAAA,KAAA,CAAM,KAAK,EAAE,CAAA;AAAA,EACf;AAEA,EAAA,OAAO,KAAA,CAAM,KAAK,IAAI,CAAA;AACxB;;;;"}
+{"version":3,"file":"intentFormat.cjs.js","sources":["../../src/lib/intentFormat.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport chalk from 'chalk';\n\nexport type OutputMode = 'human' | 'json';\n\n/**\n * Shared `--output` flag definition for commands that support both formats.\n */\nexport const outputFlag = {\n  output: {\n    type: String,\n    description: 'Output format: \"human\" (default) or \"json\"',\n  },\n};\n\nexport function parseOutputFlag(flags: Record<string, unknown>): OutputMode {\n  const output = flags.output;\n  if (output === undefined || output === 'human') return 'human';\n  if (output === 'json') return 'json';\n  throw new Error(\n    `Invalid --output value \"${String(output)}\", expected \"human\" or \"json\"`,\n  );\n}\n\n/**\n * Describes one fetched page of a paginated list.\n */\nexport type PageResult = {\n  /** Number of items in this page */\n  count: number;\n  /** Total number of items across all pages, if known */\n  total?: number;\n  /** Cursor for the next page, if there is one */\n  nextCursor?: string;\n};\n\n/**\n * Prints a single page of results followed by a footer with the number of\n * results shown, unless the page is empty. When more results exist, a hint with the `--cursor` value to\n * continue from is printed.\n */\nexport async function printPage<T extends PageResult>(\n  fetchPage: (cursor?: string) => Promise<T>,\n  render: (page: T) => void,\n  cursor?: string,\n): Promise<void> {\n  const page = await fetchPage(cursor);\n  render(page);\n\n  if (page.count > 0) {\n    const total = page.total === undefined ? '' : ` of ${page.total}`;\n    process.stdout.write(`${chalk.dim(`Showing ${page.count}${total}`)}\\n`);\n  }\n  if (page.nextCursor) {\n    process.stdout.write(\n      `${chalk.dim(\n        `More results available, use --cursor ${page.nextCursor} to show them`,\n      )}\\n`,\n    );\n  }\n}\n\nexport function writeJson(data: unknown): void {\n  process.stdout.write(`${JSON.stringify(data, null, 2)}\\n`);\n}\n\nexport function formatSearchResults(\n  results: Array<Record<string, unknown>>,\n): string {\n  if (results.length === 0) {\n    return `${chalk.yellow('No results found.')}\\n`;\n  }\n\n  const lines: string[] = [];\n  for (const result of results) {\n    const doc = result.document as Record<string, unknown> | undefined;\n    const title = String(doc?.title ?? result.title ?? '');\n    const location = String(doc?.location ?? result.location ?? '');\n    const text = String(doc?.text ?? result.text ?? '');\n    const snippet = text.length > 120 ? `${text.slice(0, 120)}...` : text;\n\n    lines.push(chalk.bold(title));\n    if (location) lines.push(`  ${chalk.dim(location)}`);\n    if (snippet) lines.push(`  ${snippet}`);\n    lines.push('');\n  }\n\n  return lines.join('\\n');\n}\n"],"names":["chalk"],"mappings":";;;;;;;;AAuBO,MAAM,UAAA,GAAa;AAAA,EACxB,MAAA,EAAQ;AAAA,IACN,IAAA,EAAM,MAAA;AAAA,IACN,WAAA,EAAa;AAAA;AAEjB;AAEO,SAAS,gBAAgB,KAAA,EAA4C;AAC1E,EAAA,MAAM,SAAS,KAAA,CAAM,MAAA;AACrB,EAAA,IAAI,MAAA,KAAW,MAAA,IAAa,MAAA,KAAW,OAAA,EAAS,OAAO,OAAA;AACvD,EAAA,IAAI,MAAA,KAAW,QAAQ,OAAO,MAAA;AAC9B,EAAA,MAAM,IAAI,KAAA;AAAA,IACR,CAAA,wBAAA,EAA2B,MAAA,CAAO,MAAM,CAAC,CAAA,6BAAA;AAAA,GAC3C;AACF;AAmBA,eAAsB,SAAA,CACpB,SAAA,EACA,MAAA,EACA,MAAA,EACe;AACf,EAAA,MAAM,IAAA,GAAO,MAAM,SAAA,CAAU,MAAM,CAAA;AACnC,EAAA,MAAA,CAAO,IAAI,CAAA;AAEX,EAAA,IAAI,IAAA,CAAK,QAAQ,CAAA,EAAG;AAClB,IAAA,MAAM,QAAQ,IAAA,CAAK,KAAA,KAAU,SAAY,EAAA,GAAK,CAAA,IAAA,EAAO,KAAK,KAAK,CAAA,CAAA;AAC/D,IAAA,OAAA,CAAQ,MAAA,CAAO,KAAA,CAAM,CAAA,EAAGA,sBAAA,CAAM,GAAA,CAAI,CAAA,QAAA,EAAW,IAAA,CAAK,KAAK,CAAA,EAAG,KAAK,CAAA,CAAE,CAAC;AAAA,CAAI,CAAA;AAAA,EACxE;AACA,EAAA,IAAI,KAAK,UAAA,EAAY;AACnB,IAAA,OAAA,CAAQ,MAAA,CAAO,KAAA;AAAA,MACb,GAAGA,sBAAA,CAAM,GAAA;AAAA,QACP,CAAA,qCAAA,EAAwC,KAAK,UAAU,CAAA,aAAA;AAAA,OACxD;AAAA;AAAA,KACH;AAAA,EACF;AACF;AAEO,SAAS,UAAU,IAAA,EAAqB;AAC7C,EAAA,OAAA,CAAQ,MAAA,CAAO,MAAM,CAAA,EAAG,IAAA,CAAK,UAAU,IAAA,EAAM,IAAA,EAAM,CAAC,CAAC;AAAA,CAAI,CAAA;AAC3D;AAEO,SAAS,oBACd,OAAA,EACQ;AACR,EAAA,IAAI,OAAA,CAAQ,WAAW,CAAA,EAAG;AACxB,IAAA,OAAO,CAAA,EAAGA,sBAAA,CAAM,MAAA,CAAO,mBAAmB,CAAC;AAAA,CAAA;AAAA,EAC7C;AAEA,EAAA,MAAM,QAAkB,EAAC;AACzB,EAAA,KAAA,MAAW,UAAU,OAAA,EAAS;AAC5B,IAAA,MAAM,MAAM,MAAA,CAAO,QAAA;AACnB,IAAA,MAAM,QAAQ,MAAA,CAAO,GAAA,EAAK,KAAA,IAAS,MAAA,CAAO,SAAS,EAAE,CAAA;AACrD,IAAA,MAAM,WAAW,MAAA,CAAO,GAAA,EAAK,QAAA,IAAY,MAAA,CAAO,YAAY,EAAE,CAAA;AAC9D,IAAA,MAAM,OAAO,MAAA,CAAO,GAAA,EAAK,IAAA,IAAQ,MAAA,CAAO,QAAQ,EAAE,CAAA;AAClD,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,MAAA,GAAS,GAAA,GAAM,CAAA,EAAG,KAAK,KAAA,CAAM,CAAA,EAAG,GAAG,CAAC,CAAA,GAAA,CAAA,GAAQ,IAAA;AAEjE,IAAA,KAAA,CAAM,IAAA,CAAKA,sBAAA,CAAM,IAAA,CAAK,KAAK,CAAC,CAAA;AAC5B,IAAA,IAAI,QAAA,QAAgB,IAAA,CAAK,CAAA,EAAA,EAAKA,uBAAM,GAAA,CAAI,QAAQ,CAAC,CAAA,CAAE,CAAA;AACnD,IAAA,IAAI,OAAA,EAAS,KAAA,CAAM,IAAA,CAAK,CAAA,EAAA,EAAK,OAAO,CAAA,CAAE,CAAA;AACtC,IAAA,KAAA,CAAM,KAAK,EAAE,CAAA;AAAA,EACf;AAEA,EAAA,OAAO,KAAA,CAAM,KAAK,IAAI,CAAA;AACxB;;;;;;"}

package/dist/lib/resolveAuth.cjs.js

@@ -2,11 +2,18 @@
 
 var cliNode = require('@backstage/cli-node');
 
-async function resolveAuth(instanceFlag) {
-  const auth = await cliNode.CliAuth.create({ instanceName: instanceFlag });
+async function resolveAuth(instanceFlag2) {
+  const auth = await cliNode.CliAuth.create({ instanceName: instanceFlag2 });
   const accessToken = await auth.getAccessToken();
   return { baseUrl: auth.getBaseUrl(), accessToken };
 }
+const instanceFlag = {
+  instance: {
+    type: String,
+    description: 'Name of the Backstage instance to use (defaults to the one chosen with "auth select")'
+  }
+};
 
+exports.instanceFlag = instanceFlag;
 exports.resolveAuth = resolveAuth;
 //# sourceMappingURL=resolveAuth.cjs.js.map

package/dist/lib/resolveAuth.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolveAuth.cjs.js","sources":["../../src/lib/resolveAuth.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { CliAuth } from '@backstage/cli-node';\n\nexport async function resolveAuth(instanceFlag?: string): Promise<{\n  baseUrl: string;\n  accessToken: string;\n}> {\n  const auth = await CliAuth.create({ instanceName: instanceFlag });\n  const accessToken = await auth.getAccessToken();\n  return { baseUrl: auth.getBaseUrl(), accessToken };\n}\n"],"names":["CliAuth"],"mappings":";;;;AAkBA,eAAsB,YAAY,YAAA,EAG/B;AACD,EAAA,MAAM,OAAO,MAAMA,eAAA,CAAQ,OAAO,EAAE,YAAA,EAAc,cAAc,CAAA;AAChE,EAAA,MAAM,WAAA,GAAc,MAAM,IAAA,CAAK,cAAA,EAAe;AAC9C,EAAA,OAAO,EAAE,OAAA,EAAS,IAAA,CAAK,UAAA,IAAc,WAAA,EAAY;AACnD;;"}
+{"version":3,"file":"resolveAuth.cjs.js","sources":["../../src/lib/resolveAuth.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { CliAuth } from '@backstage/cli-node';\n\nexport async function resolveAuth(instanceFlag?: string): Promise<{\n  baseUrl: string;\n  accessToken: string;\n}> {\n  const auth = await CliAuth.create({ instanceName: instanceFlag });\n  const accessToken = await auth.getAccessToken();\n  return { baseUrl: auth.getBaseUrl(), accessToken };\n}\n\n/**\n * Shared `--instance` flag definition, to be spread into each command's flags.\n */\nexport const instanceFlag = {\n  instance: {\n    type: String,\n    description:\n      'Name of the Backstage instance to use (defaults to the one chosen with \"auth select\")',\n  },\n};\n"],"names":["instanceFlag","CliAuth"],"mappings":";;;;AAkBA,eAAsB,YAAYA,aAAAA,EAG/B;AACD,EAAA,MAAM,OAAO,MAAMC,eAAA,CAAQ,OAAO,EAAE,YAAA,EAAcD,eAAc,CAAA;AAChE,EAAA,MAAM,WAAA,GAAc,MAAM,IAAA,CAAK,cAAA,EAAe;AAC9C,EAAA,OAAO,EAAE,OAAA,EAAS,IAAA,CAAK,UAAA,IAAc,WAAA,EAAY;AACnD;AAKO,MAAM,YAAA,GAAe;AAAA,EAC1B,QAAA,EAAU;AAAA,IACR,IAAA,EAAM,MAAA;AAAA,IACN,WAAA,EACE;AAAA;AAEN;;;"}

package/dist/package.json.cjs.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var name = "@backstage/cli-module-search";
-var version = "0.2.0-next.0";
+var version = "0.2.1-next.0";
 var description = "CLI module for searching Backstage content";
 var backstage = {
 	role: "cli-module"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/cli-module-search",
-  "version": "0.2.0-next.0",
+  "version": "0.2.1-next.0",
   "description": "CLI module for searching Backstage content",
   "backstage": {
     "role": "cli-module"
@@ -33,13 +33,13 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/cli-node": "0.3.5-next.0",
-    "@backstage/errors": "1.3.2-next.0",
+    "@backstage/cli-node": "0.3.6-next.0",
+    "@backstage/errors": "1.3.2",
     "chalk": "^4.0.0",
     "cleye": "^2.6.0"
   },
   "devDependencies": {
-    "@backstage/cli": "0.36.7-next.0"
+    "@backstage/cli": "0.36.8-next.0"
   },
   "typesVersions": {
     "*": {