@seamapi/cli 0.11.0 → 0.13.0

package/lib/completion/render-zsh.js

@@ -0,0 +1,121 @@
+import { flagTokens, } from '../command-spec.js';
+import { describeForShell } from './describe.js';
+export const renderZshCompletion = (spec) => {
+    const valuelessTokens = spec.globalFlags
+        .filter(({ takesValue }) => !takesValue)
+        .flatMap(flagTokens)
+        .sort();
+    return `${[
+        header,
+        renderCase('_seam_subcommands', subcommandBranches(spec)),
+        renderCase('_seam_flags', flagBranches(spec)),
+        renderCase('_seam_flag_values', flagValueBranches(spec)),
+        `_seam_global_flags() {\n  _seam_reply+=(${describeFlags(spec.globalFlags)})\n}`,
+        completionFunction(valuelessTokens),
+        dispatch,
+    ].join('\n\n')}\n`;
+};
+const header = `#compdef seam
+
+# zsh completion for the seam command.
+#
+# Generated by @seamapi/cli from the Seam API definitions.
+# Do not edit: regenerate with 'seam completion zsh'.
+#
+# Load it for the current shell with
+#
+#   source <(seam completion zsh)
+#
+# or install it for every shell with
+#
+#   seam completion zsh > "\${fpath[1]}/_seam"`;
+const completionFunction = (valuelessTokens) => `_seam() {
+  local -a _seam_reply
+  local -a valueless
+  local command previous word
+  local -i index
+
+  valueless=(${valuelessTokens.join(' ')})
+
+  # The command path is the run of words before the first flag.
+  command=''
+  for (( index = 2; index < CURRENT; index++ )); do
+    word="\${words[index]}"
+    if [[ "$word" == -* ]]; then
+      break
+    fi
+    command="\${command:+$command }$word"
+  done
+
+  previous=''
+  if (( CURRENT > 1 )); then
+    previous="\${words[CURRENT - 1]}"
+  fi
+
+  # Completing the value of a flag that takes one.
+  if [[ "$previous" == -* ]] && (( \${valueless[(Ie)$previous]} == 0 )); then
+    _seam_flag_values "$command $previous"
+    if (( \${#_seam_reply} )); then
+      _describe -t values 'value' _seam_reply
+    fi
+    return
+  fi
+
+  if [[ "\${words[CURRENT]}" == -* ]]; then
+    _seam_flags "$command"
+    _seam_global_flags
+    _describe -t options 'option' _seam_reply
+    return
+  fi
+
+  _seam_subcommands "$command"
+  if (( \${#_seam_reply} )); then
+    _describe -t commands 'command' _seam_reply
+    return
+  fi
+
+  _seam_flags "$command"
+  _seam_global_flags
+  _describe -t options 'option' _seam_reply
+}`;
+// The script runs in three ways. Autoloaded from fpath as _seam, it must
+// complete the in-flight request: funcstack holds _seam. Evaluated by the
+// loader stub inside the autoloaded _seam, the same applies, but eval pushes
+// '(eval)' onto funcstack, so search the whole stack rather than the top.
+// Sourced into a shell, funcstack holds no _seam: register with compdef.
+const dispatch = `if (( \${funcstack[(I)_seam]} )); then
+  _seam "$@"
+else
+  compdef _seam seam
+fi`;
+const subcommandBranches = (spec) => spec.groups.map((group) => ({
+    pattern: group.path.join(' '),
+    entries: group.subcommands.map(({ name, description }) => describe(name, description)),
+}));
+const flagBranches = (spec) => spec.commands
+    .filter(({ flags }) => flags.length > 0)
+    .map((command) => ({
+    pattern: command.path.join(' '),
+    entries: [describeFlags(command.flags)],
+}));
+const flagValueBranches = (spec) => spec.commands.flatMap((command) => command.flags
+    .filter(({ values }) => values.length > 0)
+    .flatMap((flag) => flagTokens(flag).map((token) => ({
+    pattern: `${command.path.join(' ')} ${token}`,
+    entries: flag.values.map((value) => `'${value}'`),
+}))));
+const describeFlags = (flags) => flags
+    .flatMap((flag) => flagTokens(flag).map((token) => describe(token, flag.description)))
+    .join(' ');
+const describe = (value, description) => {
+    const summary = describeForShell(description);
+    return summary === '' ? `'${value}'` : `'${value}:${summary}'`;
+};
+const renderCase = (name, branches) => [
+    `${name}() {`,
+    `  case "$1" in`,
+    ...branches.map(({ pattern, entries }) => `    ('${pattern}') _seam_reply+=(${entries.join(' ')}) ;;`),
+    `  esac`,
+    `}`,
+].join('\n');
+//# sourceMappingURL=render-zsh.js.map

package/lib/completion/render-zsh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-zsh.js","sourceRoot":"","sources":["../../src/lib/completion/render-zsh.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,UAAU,GACX,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEhD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,IAAiB,EAAU,EAAE;IAC/D,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW;SACrC,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC;SACvC,OAAO,CAAC,UAAU,CAAC;SACnB,IAAI,EAAE,CAAA;IAET,OAAO,GAAG;QACR,MAAM;QACN,UAAU,CAAC,mBAAmB,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACzD,UAAU,CAAC,aAAa,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC;QAC7C,UAAU,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACxD,2CAA2C,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM;QAChF,kBAAkB,CAAC,eAAe,CAAC;QACnC,QAAQ;KACT,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAA;AACpB,CAAC,CAAA;AAED,MAAM,MAAM,GAAG;;;;;;;;;;;;;+CAagC,CAAA;AAE/C,MAAM,kBAAkB,GAAG,CAAC,eAAyB,EAAU,EAAE,CAC/D;;;;;;eAMa,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0CtC,CAAA;AAEF,yEAAyE;AACzE,0EAA0E;AAC1E,6EAA6E;AAC7E,0EAA0E;AAC1E,yEAAyE;AACzE,MAAM,QAAQ,GAAG;;;;GAId,CAAA;AAOH,MAAM,kBAAkB,GAAG,CAAC,IAAiB,EAAY,EAAE,CACzD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1B,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IAC7B,OAAO,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,CACvD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,CAC5B;CACF,CAAC,CAAC,CAAA;AAEL,MAAM,YAAY,GAAG,CAAC,IAAiB,EAAY,EAAE,CACnD,IAAI,CAAC,QAAQ;KACV,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;KACvC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IAC/B,OAAO,EAAE,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;CACxC,CAAC,CAAC,CAAA;AAEP,MAAM,iBAAiB,GAAG,CAAC,IAAiB,EAAY,EAAE,CACxD,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAChC,OAAO,CAAC,KAAK;KACV,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;KACzC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAChB,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC/B,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,EAAE;IAC7C,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,GAAG,CAAC;CAClD,CAAC,CAAC,CACJ,CACJ,CAAA;AAEH,MAAM,aAAa,GAAG,CAAC,KAAoB,EAAU,EAAE,CACrD,KAAK;KACF,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAChB,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CACnE;KACA,IAAI,CAAC,GAAG,CAAC,CAAA;AAEd,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAE,WAAmB,EAAU,EAAE;IAC9D,MAAM,OAAO,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAA;IAC7C,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,OAAO,GAAG,CAAA;AAChE,CAAC,CAAA;AAED,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,QAAkB,EAAU,EAAE,CAC9D;IACE,GAAG,IAAI,MAAM;IACb,gBAAgB;IAChB,GAAG,QAAQ,CAAC,GAAG,CACb,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CACvB,SAAS,OAAO,oBAAoB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAC9D;IACD,QAAQ;IACR,GAAG;CACJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA"}

package/lib/render-help.d.ts

@@ -0,0 +1,8 @@
+import { type CommandSpec } from './command-spec.js';
+/**
+ * Render the help guide for a command path, or `null` when no command or
+ * group goes by that path.
+ *
+ * An empty path is the guide for `seam` itself.
+ */
+export declare const renderHelp: (path: string[], spec: CommandSpec) => string | null;

package/lib/render-help.js

@@ -0,0 +1,150 @@
+import commandLineUsage, {} from 'command-line-usage';
+import { findCommand, findGroup, } from './command-spec.js';
+/**
+ * Render the help guide for a command path, or `null` when no command or
+ * group goes by that path.
+ *
+ * An empty path is the guide for `seam` itself.
+ */
+export const renderHelp = (path, spec) => {
+    const group = findGroup(spec, path);
+    if (group != null)
+        return commandLineUsage(groupSections(group, spec));
+    const command = findCommand(spec, path);
+    if (command != null)
+        return commandLineUsage(commandSections(command, spec));
+    return null;
+};
+const overview = 'Every seam command runs as soon as every required property is given, and otherwise prompts you for what is missing with helpful suggestions. Pass -i to always review properties first, or -y to never be prompted.';
+const outputSection = {
+    header: 'Output',
+    content: [
+        'Only the response is written to stdout, so it is safe to pipe. Prompts, progress, and other information are written to stderr.',
+        'The response is trimmed to the response key and pagination.',
+        'Request params may be piped or redirected in as a JSON object. Params given as arguments win over params read from stdin.',
+    ],
+};
+const examples = [
+    { name: 'seam', summary: 'Interactively select commands to execute.' },
+    { name: 'seam login', summary: 'Login to Seam.' },
+    { name: 'seam wizard', summary: 'Set up Seam in the current project.' },
+    { name: 'seam select workspace', summary: 'Select your workspace.' },
+    {
+        name: 'seam connect-webviews create',
+        summary: 'Create a connect webview to connect devices.',
+    },
+    { name: 'seam devices list', summary: 'List devices in your workspace.' },
+    {
+        name: 'seam devices list {bold --interactive}',
+        summary: 'Review and edit filters before listing devices.',
+    },
+    {
+        name: 'seam devices list {bold --non-interactive}',
+        summary: 'List devices, failing instead of prompting.',
+    },
+    {
+        name: 'seam locks unlock-door {bold --device-id} $MY_DOOR',
+        summary: 'Unlock a lock.',
+    },
+    {
+        name: "seam access-codes create {bold --code} '1234' {bold --name} 'My Code'",
+        summary: 'Create an access code.',
+    },
+    {
+        name: 'seam devices list > devices.json',
+        summary: 'Write the response to a file as JSON.',
+    },
+    {
+        name: 'cat params.json | seam locks unlock-door',
+        summary: 'Pipe request params in as JSON.',
+    },
+    {
+        name: 'seam completion bash',
+        summary: 'Print a shell completion script for bash, fish, or zsh.',
+    },
+];
+const groupSections = (group, spec) => {
+    const isRoot = group.path.length === 0;
+    const name = ['seam', ...group.path].join(' ');
+    return [
+        isRoot
+            ? { header: 'Seam CLI', content: overview }
+            : { header: name, content: `Commands under ${name}.` },
+        { header: 'Usage', content: `${name} <command> [options]` },
+        ...commandSectionsForGroup(group, isRoot),
+        optionSection(spec.globalFlags),
+        ...(isRoot
+            ? [outputSection, { header: 'Command List Examples', content: examples }]
+            : []),
+        { content: `Run '${name} <command> --help' to see a command in detail.` },
+    ];
+};
+const commandSectionsForGroup = (group, isRoot) => {
+    const content = (subcommands) => subcommands.map(({ name, description }) => ({ name, summary: description }));
+    // The root guide separates the commands of the CLI itself from the commands
+    // that call the Seam API. Anywhere deeper the split adds nothing: a group
+    // holds commands of one kind.
+    if (!isRoot) {
+        return [{ header: 'Commands', content: content(group.subcommands) }];
+    }
+    const cli = group.subcommands.filter(({ kind }) => kind === 'cli');
+    const api = group.subcommands.filter(({ kind }) => kind === 'api');
+    return [
+        { header: 'Commands', content: content(cli) },
+        { header: 'API Commands', content: content(api) },
+    ].filter((section) => section.content.length > 0);
+};
+const commandSections = (command, spec) => {
+    const name = ['seam', ...command.path].join(' ');
+    const hasFlags = command.flags.length > 0;
+    return [
+        {
+            header: name,
+            content: [command.title, command.description].filter((line) => line !== ''),
+        },
+        { header: 'Usage', content: `${name} [options]` },
+        // The command's own parameters are what the request is made of, so keep
+        // them apart from the options every seam command takes.
+        ...(hasFlags ? [optionSection(command.flags, 'Parameters')] : []),
+        optionSection(spec.globalFlags),
+        ...(hasFlags
+            ? [
+                {
+                    content: 'Any required parameter left out is prompted for interactively.',
+                },
+            ]
+            : []),
+    ];
+};
+const optionSection = (flags, header = 'Options') => ({
+    header,
+    optionList: flags.map(toOptionDefinition),
+});
+const maxDocumentedValues = 8;
+const toOptionDefinition = (flag) => {
+    const description = [
+        flag.isRequired ? '{bold [required]}' : '',
+        flag.description,
+        describeValues(flag),
+    ]
+        .filter((part) => part !== '')
+        .join(' ');
+    return {
+        // command-line-usage renders a nameless option as the short form alone.
+        name: flag.long ?? '',
+        ...(flag.short == null ? {} : { alias: flag.short }),
+        // A flag with no value must be typed as a boolean, or the guide labels it
+        // as taking a string.
+        type: flag.takesValue ? String : Boolean,
+        ...(flag.takesValue ? { typeLabel: '{underline value}' } : {}),
+        description,
+    };
+};
+const describeValues = (flag) => {
+    if (flag.values.length === 0)
+        return '';
+    const shown = flag.values.slice(0, maxDocumentedValues).join(', ');
+    const rest = flag.values.length - maxDocumentedValues;
+    return rest > 0 ? `One of: ${shown}, and ${rest} more.` : `One of: ${shown}.`;
+};
+//# sourceMappingURL=render-help.js.map

package/lib/render-help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-help.js","sourceRoot":"","sources":["../src/lib/render-help.ts"],"names":[],"mappings":"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"}

package/lib/version.d.ts

@@ -1,4 +1,4 @@
-declare const seamapiCliVersion = "0.11.0";
+declare const seamapiCliVersion = "0.13.0";
 declare const seamapiBlueprintVersion = "1.2.0";
 export { seamapiBlueprintVersion };
 export default seamapiCliVersion;

package/lib/version.js

@@ -1,5 +1,5 @@
 // Versions are replaced with generated values when the package is packed.
-const seamapiCliVersion = '0.11.0';
+const seamapiCliVersion = '0.13.0';
 const seamapiBlueprintVersion = '1.2.0';
 export { seamapiBlueprintVersion };
 export default seamapiCliVersion;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamapi/cli",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "A command line interface (CLI) for interacting with the Seam API.",
   "type": "module",
   "main": "index.js",
@@ -45,6 +45,7 @@
     "index.js.map",
     "index.d.ts",
     "bin",
+    "completions",
     "lib",
     "src",
     "!test",

package/src/bin/cli.ts

@@ -3,9 +3,14 @@ import { randomBytes } from 'node:crypto'
 import { isDeepStrictEqual as isEqual } from 'node:util'
 
 import chalk from 'chalk'
-import commandLineUsage from 'command-line-usage'
 import type { ParsedArgs } from 'minimist'
 
+import { getCommandSpec } from 'lib/command-spec.js'
+import {
+  completionShells,
+  isCompletionShell,
+  renderCompletion,
+} from 'lib/completion/index.js'
 import { getConfigStore } from 'lib/config/index.js'
 import { getApiBlueprint } from 'lib/get-api-blueprint.js'
 import { getResponseKey } from 'lib/get-response-key.js'
@@ -20,6 +25,7 @@ import { interactForWorkspaceId } from 'lib/interact-for-workspace-id.js'
 import { createOutput } from 'lib/output/create-output.js'
 import { getOutput, setOutput } from 'lib/output/get-output.js'
 import { resolveOutputFormat } from 'lib/output/resolve-output-format.js'
+import { renderHelp } from 'lib/render-help.js'
 import type { ContextHelpers } from 'lib/types.js'
 import {
   cliFlags,
@@ -34,109 +40,35 @@ import { RequestSeamApi } from 'lib/util/request-seam-api.js'
 import { validateToken } from 'lib/validate-token.js'
 import seamapiCliVersion from 'lib/version.js'
 
-const sections = [
-  {
-    header: 'Seam CLI',
-    content:
-      'Every seam command runs as soon as every required property is given, and otherwise prompts you for what is missing with helpful suggestions. Pass -i to always review properties first, or -y to never be prompted. ',
-  },
-  {
-    header: 'Options',
-    optionList: [
-      {
-        name: 'help',
-        description: 'Display this help guide.',
-        alias: 'h',
-        type: Boolean,
-      },
-      {
-        name: 'interactive',
-        description:
-          'Always prompt to review and edit properties, prefilled with the given arguments.',
-        alias: 'i',
-        type: Boolean,
-      },
-      {
-        name: 'non-interactive',
-        description:
-          'Never prompt: exit with an error if the command or any required property is missing.',
-        alias: 'y',
-        type: Boolean,
-      },
-      {
-        name: 'json',
-        description:
-          'Write the response to stdout as JSON. Enabled automatically when stdout is not a terminal, disable with {bold --no-json}.',
-        type: Boolean,
-      },
-      {
-        name: 'update',
-        description: 'Force an update of the cached Seam API definitions.',
-        type: Boolean,
-      },
-    ],
-  },
-  {
-    header: 'Output',
-    content: [
-      'Only the response is written to stdout, so it is safe to pipe. Prompts, progress, and other information are written to stderr.',
-      'The response is trimmed to the response key and pagination.',
-      'Request params may be piped or redirected in as a JSON object. Params given as arguments win over params read from stdin.',
-    ],
-  },
-  {
-    header: 'Command List Examples',
-    content: [
-      { name: 'seam', summary: 'Interactively select commands to execute.' },
-      { name: 'seam login', summary: 'Login to Seam.' },
-      {
-        name: 'seam wizard',
-        summary: 'Set up Seam in the current project.',
-      },
-      { name: 'seam select workspace', summary: 'Select your workspace.' },
-      {
-        name: 'seam connect-webviews create',
-        summary: 'Create a connect webview to connect devices.',
-      },
-      { name: 'seam devices list', summary: 'List devices in your workspace.' },
-      {
-        name: 'seam devices list {bold --interactive}',
-        summary: 'Review and edit filters before listing devices.',
-      },
-      {
-        name: 'seam devices list {bold --non-interactive}',
-        summary: 'List devices, failing instead of prompting.',
-      },
-      {
-        name: 'seam locks unlock-door {bold --device-id} $MY_DOOR',
-        summary: 'Unlock a lock.',
-      },
-      {
-        name: "seam access-codes create {bold --code} '1234' {bold --name} 'My Code'",
-        summary: 'Create an access code.',
-      },
-      {
-        name: 'seam access-codes list {bold --device-id} $MY_DOOR',
-        summary: 'List you access codes.',
-      },
-      {
-        name: 'seam devices list > devices.json',
-        summary: 'Write the response to a file as JSON.',
-      },
-      {
-        name: 'cat params.json | seam locks unlock-door',
-        summary: 'Pipe request params in as JSON.',
-      },
-    ],
-  },
-]
-
 async function cli(args: ParsedArgs) {
   const config = getConfigStore()
   const output = getOutput()
 
-  if (args['help'] || args['h']) {
-    output.text(commandLineUsage(sections))
+  const update = args['update'] === true
+
+  const helpFlag = args['help'] ?? args['h']
+  if (helpFlag != null) {
+    // Help comes from the cached API definitions so that it works without
+    // logging in, and offline once the cache is warm.
+    const spec = getCommandSpec(await getApiBlueprint(false, { update }))
+
+    // minimist reads the word after --help as its value, so 'seam --help
+    // devices' asks about devices just as 'seam devices --help' does.
+    const commandPath = [
+      ...args._,
+      ...(typeof helpFlag === 'string' ? [helpFlag] : []),
+    ].map(toCommandWord)
+
+    const help = renderHelp(commandPath, spec)
+
+    if (help == null) {
+      output.error(chalk.red(`Unknown command: seam ${commandPath.join(' ')}`))
+      output.error(`Run 'seam --help' to see the available commands.`)
+      process.exitCode = 1
+      return
+    }
+
+    output.text(help)
     return
   }
 
@@ -145,6 +77,24 @@ async function cli(args: ParsedArgs) {
     return
   }
 
+  if (args._[0] === 'completion') {
+    const shell = args._[1]
+
+    if (!isCompletionShell(shell)) {
+      output.error(`Usage: seam completion <${completionShells.join('|')}>`)
+      process.exitCode = 1
+      return
+    }
+
+    // Completions always come from the cached API definitions so that they
+    // can be generated without logging in. They may lag the definitions
+    // served by Seam when config use-remote-api-defs is enabled.
+    output.text(
+      renderCompletion(shell, await getApiBlueprint(false, { update })),
+    )
+    return
+  }
+
   if (
     args._[0] === 'config' &&
     args._[1] === 'set' &&
@@ -171,7 +121,7 @@ async function cli(args: ParsedArgs) {
     return
   }
 
-  args._ = args._.map((arg) => arg.toLowerCase().replace(/_/g, '-'))
+  args._ = args._.map(toCommandWord)
   for (const k in args) {
     args[k.toLowerCase().replace(/-/g, '_')] = args[k]
   }
@@ -179,9 +129,6 @@ async function cli(args: ParsedArgs) {
   const use_remote_api_defs =
     args['remote_api_defs'] ?? config.get('use_remote_api_defs')
 
-  const update = args['update'] === true
-  delete args['update']
-
   const blueprint = await getApiBlueprint(use_remote_api_defs ?? false, {
     update,
   })
@@ -336,6 +283,9 @@ async function cli(args: ParsedArgs) {
   }
 }
 
+const toCommandWord = (arg: string): string =>
+  arg.toLowerCase().replace(/_/g, '-')
+
 const handleConnectWebviewResponse = async (
   connect_webview: any,
   interactivity: Interactivity,