Page Not Found
We could not find what you were looking for.
Please contact the owner of the site that linked you to the original URL and let them know their link is broken.
oclif generate NAME",id:"oclif-generate-name",level:2},{value:"oclif generate command NAME",id:"oclif-generate-command-name",level:2},{value:"oclif generate hook NAME",id:"oclif-generate-hook-name",level:2}];function s(e){const n={a:"a",code:"code",em:"em",h2:"h2",li:"li",p:"p",pre:"pre",ul:"ul",...(0,r.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#oclif-generate-name",children:(0,t.jsx)(n.code,{children:"oclif generate NAME"})})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#oclif-generate-command-name",children:(0,t.jsx)(n.code,{children:"oclif generate command NAME"})})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#oclif-generate-hook-name",children:(0,t.jsx)(n.code,{children:"oclif generate hook NAME"})})}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"oclif-generate-name",children:(0,t.jsx)(n.code,{children:"oclif generate NAME"})}),"\n",(0,t.jsx)(n.p,{children:"generate a new CLI"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{children:"USAGE\n $ oclif generate [NAME]\n\nARGUMENTS\n NAME directory name of new project\n\nDESCRIPTION\n generate a new CLI\n\n This will clone the template repo 'oclif/hello-world' and update package properties\n"})}),"\n",(0,t.jsx)(n.p,{children:(0,t.jsxs)(n.em,{children:["See code: ",(0,t.jsx)(n.a,{href:"https://github.com/oclif/oclif/blob/v2.2.0/src/commands/generate.ts",children:"src/commands/generate.ts"})]})}),"\n",(0,t.jsx)(n.h2,{id:"oclif-generate-command-name",children:(0,t.jsx)(n.code,{children:"oclif generate command NAME"})}),"\n",(0,t.jsx)(n.p,{children:"add a command to an existing CLI or plugin"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{children:"USAGE\n $ oclif generate command [NAME] [--force]\n\nARGUMENTS\n NAME name of command\n\nFLAGS\n --force overwrite existing files\n\nDESCRIPTION\n add a command to an existing CLI or plugin\n"})}),"\n",(0,t.jsx)(n.h2,{id:"oclif-generate-hook-name",children:(0,t.jsx)(n.code,{children:"oclif generate hook NAME"})}),"\n",(0,t.jsx)(n.p,{children:"add a hook to an existing CLI or plugin"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{children:"USAGE\n $ oclif generate hook [NAME] [--force] [--event pattern Strategy",id:"pattern-strategy",level:3},{value:"explicit Strategy",id:"explicit-strategy",level:3},{value:"Hooks",id:"hooks",level:4},{value:"Bundling",id:"bundling",level:4},{value:"single Strategy",id:"single-strategy",level:3},{value:"Note about oclif.manifest.json",id:"note-about-oclifmanifestjson",level:3}];function r(e){const n={a:"a",code:"code",em:"em",h3:"h3",h4:"h4",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",...(0,o.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.p,{children:"When oclif loads a plugin is must find all the commands within that plugin that can be executed. There a three strategies for discovering these commands:"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"pattern"})," - this is the default behavior that finds commands based on glob patterns."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"explicit"})," - find commands that are exported from a specified file."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"single"})," - CLI contains a single command executed by top-level bin."]}),"\n"]}),"\n",(0,t.jsxs)(n.h3,{id:"pattern-strategy",children:[(0,t.jsx)(n.code,{children:"pattern"})," Strategy"]}),"\n",(0,t.jsxs)(n.p,{children:["The ",(0,t.jsx)(n.code,{children:"pattern"})," strategy tells oclif to use a predefined set of globs to find command files in a specified directory. This is the default behavior of oclif unless otherwise stated."]}),"\n",(0,t.jsxs)(n.p,{children:["Plugins can point the ",(0,t.jsx)(n.code,{children:"commands"})," property to a directory"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "oclif": {\n "commands": "./dist/commands",\n }\n}\n'})}),"\n",(0,t.jsxs)(n.p,{children:["This will tell oclif to look for commands in that directory (this is skipped if an ",(0,t.jsx)(n.code,{children:"oclif.manifest.json"})," is present)"]}),"\n",(0,t.jsx)(n.p,{children:"Alternatively, you can set this configuration which will do the exact same thing:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "oclif": {\n "commands": {\n "strategy": "pattern",\n "target": "./dist/commands"\n }\n }\n}\n'})}),"\n",(0,t.jsxs)(n.p,{children:["You also have the ability to set ",(0,t.jsx)(n.code,{children:"globPatterns"}),", which override the glob patterns that oclif uses when searching for command files:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "oclif": {\n "commands": {\n "strategy": "pattern",\n "target": "./dist/commands",\n "globPatterns": [\n "**/*.+(js|cjs|mjs|ts|tsx|mts|cts)",\n "!**/*.+(d.*|test.*|spec.*|helpers.*)?(x)"\n ]\n }\n }\n}\n'})}),"\n",(0,t.jsx)(n.p,{children:"This is useful if you like to put test or helper files in the same directory as your command files."}),"\n",(0,t.jsxs)(n.h3,{id:"explicit-strategy",children:[(0,t.jsx)(n.code,{children:"explicit"})," Strategy"]}),"\n",(0,t.jsxs)(n.p,{children:["The ",(0,t.jsx)(n.code,{children:"explicit"})," strategy tells oclif to import commands from a single file. In this case the ",(0,t.jsx)(n.code,{children:"target"})," is the file that exports the commands and ",(0,t.jsx)(n.code,{children:"identifier"})," is the name of the export (defaults to ",(0,t.jsx)(n.code,{children:"default"}),")."]}),"\n",(0,t.jsxs)(n.p,{children:["To use this you would add a new file (e.g. ",(0,t.jsx)(n.code,{children:"src/commands.ts"}),") and then add this configuration to the package.json"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "oclif": {\n "commands": {\n "strategy": "explicit",\n "target": "./dist/index.js",\n "identifier": "COMMANDS",\n }\n }\n}\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"src/index.ts"})," would then need to have an export with the same name as the ",(0,t.jsx)(n.code,{children:"identifier"})," (if not set, it defaults to ",(0,t.jsx)(n.code,{children:"default"}),") that's an object of command names to command classes, e.g."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"import Hello from './commands/hello'\nimport HelloWorld from './commands/hello/world'\n\nexport const COMMANDS = {\n hello: Hello,\n 'hello:world': HelloWorld,\n howdy: Hello, // alias the `hello` command to `howdy`\n}\n"})}),"\n",(0,t.jsxs)(n.p,{children:["The ",(0,t.jsx)(n.code,{children:"explicit"})," strategy is useful to those who can't rely on file paths because they've bundled their code (see ",(0,t.jsx)(n.a,{href:"#bundling",children:"Bundling"}),') but it can also be used if you simply prefer to be more explicit about your commands instead of relying on oclif "magically" finding commands from the file system.']}),"\n",(0,t.jsxs)(n.p,{children:["It can also be leveraged to create or modify commands at runtime (e.g. internationalize messages at runtime or add flags to a command based on an API spec - see ",(0,t.jsx)(n.code,{children:"oclif + dynamic commands"})," section below)."]}),"\n",(0,t.jsx)(n.h4,{id:"hooks",children:"Hooks"}),"\n",(0,t.jsxs)(n.p,{children:["Hooks can also be defined using the ",(0,t.jsx)(n.code,{children:"explicit"})," strategy:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'"oclif": {\n "hooks": {\n "init": {\n "target": "./dist/index.js",\n "identifier": "INIT_HOOK"\n }\n }\n}\n'})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"// src/index.ts\nimport Hello from './commands/hello'\nimport HelloWorld from './commands/hello/world'\nexport {default as INIT_HOOK} from './hooks/init/init.js'\n\nexport const COMMANDS = {\n hello: Hello,\n 'hello:world': HelloWorld,\n howdy: Hello, // alias the `hello` command to `howdy`\n}\n"})}),"\n",(0,t.jsxs)(n.p,{children:["That configuration is essentially telling oclif to look for an ",(0,t.jsx)(n.code,{children:"INIT_HOOK"})," export inside of ",(0,t.jsx)(n.code,{children:"./dist/index.js"})]}),"\n",(0,t.jsx)(n.h4,{id:"bundling",children:"Bundling"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"We do not support bundling"})," given the endless number of tools + configurations that could be used. But if you choose to use a bundler, like ",(0,t.jsx)(n.code,{children:"esbuild"})," there are a couple hard requirements - you must have a package.json in your root directory and a ",(0,t.jsx)(n.code,{children:"bin/run"})," or ",(0,t.jsx)(n.code,{children:"bin/run.js"})," bin script. ",(0,t.jsx)(n.em,{children:"This means that you will not be able to successfully bundle your entire CLI (src code, package.json, node_modules, etc) into a single file."})]}),"\n",(0,t.jsxs)(n.p,{children:["If you want to use a bundler, you can see this ",(0,t.jsx)(n.a,{href:"https://github.com/oclif/plugin-test-esbuild/",children:"example repo"}),"."]}),"\n",(0,t.jsxs)(n.h3,{id:"single-strategy",children:[(0,t.jsx)(n.code,{children:"single"})," Strategy"]}),"\n",(0,t.jsxs)(n.p,{children:["The ",(0,t.jsx)(n.code,{children:"single"})," strategy tells oclif that this CLI contains a single command that can be executed by the ",(0,t.jsx)(n.code,{children:"bin/run.js"})," (e.g. ",(0,t.jsx)(n.code,{children:"ls"})," or ",(0,t.jsx)(n.code,{children:"cat"}),")."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "oclif": {\n "commands": {\n "strategy": "single",\n "target": "./dist/index.js"\n }\n }\n}\n'})}),"\n",(0,t.jsxs)(n.p,{children:["In this example, ",(0,t.jsx)(n.code,{children:"./dist/index.js"})," exports the command class."]}),"\n",(0,t.jsxs)(n.h3,{id:"note-about-oclifmanifestjson",children:["Note about ",(0,t.jsx)(n.code,{children:"oclif.manifest.json"})]}),"\n",(0,t.jsxs)(n.p,{children:["For all strategies, the ",(0,t.jsx)(n.code,{children:"oclif.manifest.json"})," will be used to load the commands instead of the default behavior of the strategy."]})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(r,{...e})}):r(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>l,x:()=>d});var t=s(6540);const o={},i=t.createContext(o);function l(e){const n=t.useContext(i);return t.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function d(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:l(e.components),t.createElement(i.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
+"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[4260],{3602:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>c,contentTitle:()=>l,default:()=>h,frontMatter:()=>i,metadata:()=>d,toc:()=>a});var t=s(4848),o=s(8453);const i={title:"Command Discovery Strategies"},l=void 0,d={id:"command_discovery_strategies",title:"Command Discovery Strategies",description:"When oclif loads a plugin is must find all the commands within that plugin that can be executed. There a three strategies for discovering these commands:",source:"@site/../docs/command_discovery_strategies.md",sourceDirName:".",slug:"/command_discovery_strategies",permalink:"/docs/command_discovery_strategies",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/command_discovery_strategies.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711137687,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Command Discovery Strategies"},sidebar:"docs",previous:{title:"Plugin Loading",permalink:"/docs/plugin_loading"},next:{title:"Commands",permalink:"/docs/commands"}},c={},a=[{value:"pattern Strategy",id:"pattern-strategy",level:3},{value:"explicit Strategy",id:"explicit-strategy",level:3},{value:"Hooks",id:"hooks",level:4},{value:"Bundling",id:"bundling",level:4},{value:"single Strategy",id:"single-strategy",level:3},{value:"Note about oclif.manifest.json",id:"note-about-oclifmanifestjson",level:3}];function r(e){const n={a:"a",code:"code",em:"em",h3:"h3",h4:"h4",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",...(0,o.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.p,{children:"When oclif loads a plugin is must find all the commands within that plugin that can be executed. There a three strategies for discovering these commands:"}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"pattern"})," - this is the default behavior that finds commands based on glob patterns."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"explicit"})," - find commands that are exported from a specified file."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"single"})," - CLI contains a single command executed by top-level bin."]}),"\n"]}),"\n",(0,t.jsxs)(n.h3,{id:"pattern-strategy",children:[(0,t.jsx)(n.code,{children:"pattern"})," Strategy"]}),"\n",(0,t.jsxs)(n.p,{children:["The ",(0,t.jsx)(n.code,{children:"pattern"})," strategy tells oclif to use a predefined set of globs to find command files in a specified directory. This is the default behavior of oclif unless otherwise stated."]}),"\n",(0,t.jsxs)(n.p,{children:["Plugins can point the ",(0,t.jsx)(n.code,{children:"commands"})," property to a directory"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "oclif": {\n "commands": "./dist/commands",\n }\n}\n'})}),"\n",(0,t.jsxs)(n.p,{children:["This will tell oclif to look for commands in that directory (this is skipped if an ",(0,t.jsx)(n.code,{children:"oclif.manifest.json"})," is present)"]}),"\n",(0,t.jsx)(n.p,{children:"Alternatively, you can set this configuration which will do the exact same thing:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "oclif": {\n "commands": {\n "strategy": "pattern",\n "target": "./dist/commands"\n }\n }\n}\n'})}),"\n",(0,t.jsxs)(n.p,{children:["You also have the ability to set ",(0,t.jsx)(n.code,{children:"globPatterns"}),", which override the glob patterns that oclif uses when searching for command files:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "oclif": {\n "commands": {\n "strategy": "pattern",\n "target": "./dist/commands",\n "globPatterns": [\n "**/*.+(js|cjs|mjs|ts|tsx|mts|cts)",\n "!**/*.+(d.*|test.*|spec.*|helpers.*)?(x)"\n ]\n }\n }\n}\n'})}),"\n",(0,t.jsx)(n.p,{children:"This is useful if you like to put test or helper files in the same directory as your command files."}),"\n",(0,t.jsxs)(n.h3,{id:"explicit-strategy",children:[(0,t.jsx)(n.code,{children:"explicit"})," Strategy"]}),"\n",(0,t.jsxs)(n.p,{children:["The ",(0,t.jsx)(n.code,{children:"explicit"})," strategy tells oclif to import commands from a single file. In this case the ",(0,t.jsx)(n.code,{children:"target"})," is the file that exports the commands and ",(0,t.jsx)(n.code,{children:"identifier"})," is the name of the export (defaults to ",(0,t.jsx)(n.code,{children:"default"}),")."]}),"\n",(0,t.jsxs)(n.p,{children:["To use this you would add a new file (e.g. ",(0,t.jsx)(n.code,{children:"src/commands.ts"}),") and then add this configuration to the package.json"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "oclif": {\n "commands": {\n "strategy": "explicit",\n "target": "./dist/index.js",\n "identifier": "COMMANDS",\n }\n }\n}\n'})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"src/index.ts"})," would then need to have an export with the same name as the ",(0,t.jsx)(n.code,{children:"identifier"})," (if not set, it defaults to ",(0,t.jsx)(n.code,{children:"default"}),") that's an object of command names to command classes, e.g."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"import Hello from './commands/hello'\nimport HelloWorld from './commands/hello/world'\n\nexport const COMMANDS = {\n hello: Hello,\n 'hello:world': HelloWorld,\n howdy: Hello, // alias the `hello` command to `howdy`\n}\n"})}),"\n",(0,t.jsxs)(n.p,{children:["The ",(0,t.jsx)(n.code,{children:"explicit"})," strategy is useful to those who can't rely on file paths because they've bundled their code (see ",(0,t.jsx)(n.a,{href:"#bundling",children:"Bundling"}),') but it can also be used if you simply prefer to be more explicit about your commands instead of relying on oclif "magically" finding commands from the file system.']}),"\n",(0,t.jsxs)(n.p,{children:["It can also be leveraged to create or modify commands at runtime (e.g. internationalize messages at runtime or add flags to a command based on an API spec - see ",(0,t.jsx)(n.code,{children:"oclif + dynamic commands"})," section below)."]}),"\n",(0,t.jsx)(n.h4,{id:"hooks",children:"Hooks"}),"\n",(0,t.jsxs)(n.p,{children:["Hooks can also be defined using the ",(0,t.jsx)(n.code,{children:"explicit"})," strategy:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'"oclif": {\n "hooks": {\n "init": {\n "target": "./dist/index.js",\n "identifier": "INIT_HOOK"\n }\n }\n}\n'})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"// src/index.ts\nimport Hello from './commands/hello'\nimport HelloWorld from './commands/hello/world'\nexport {default as INIT_HOOK} from './hooks/init/init.js'\n\nexport const COMMANDS = {\n hello: Hello,\n 'hello:world': HelloWorld,\n howdy: Hello, // alias the `hello` command to `howdy`\n}\n"})}),"\n",(0,t.jsxs)(n.p,{children:["That configuration is essentially telling oclif to look for an ",(0,t.jsx)(n.code,{children:"INIT_HOOK"})," export inside of ",(0,t.jsx)(n.code,{children:"./dist/index.js"})]}),"\n",(0,t.jsx)(n.h4,{id:"bundling",children:"Bundling"}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.strong,{children:"We do not support bundling"})," given the endless number of tools + configurations that could be used. But if you choose to use a bundler, like ",(0,t.jsx)(n.code,{children:"esbuild"})," there are a couple hard requirements - you must have a package.json in your root directory and a ",(0,t.jsx)(n.code,{children:"bin/run"})," or ",(0,t.jsx)(n.code,{children:"bin/run.js"})," bin script. ",(0,t.jsx)(n.em,{children:"This means that you will not be able to successfully bundle your entire CLI (src code, package.json, node_modules, etc) into a single file."})]}),"\n",(0,t.jsxs)(n.p,{children:["If you want to use a bundler, you can see this ",(0,t.jsx)(n.a,{href:"https://github.com/oclif/plugin-test-esbuild/",children:"example repo"}),"."]}),"\n",(0,t.jsxs)(n.h3,{id:"single-strategy",children:[(0,t.jsx)(n.code,{children:"single"})," Strategy"]}),"\n",(0,t.jsxs)(n.p,{children:["The ",(0,t.jsx)(n.code,{children:"single"})," strategy tells oclif that this CLI contains a single command that can be executed by the ",(0,t.jsx)(n.code,{children:"bin/run.js"})," (e.g. ",(0,t.jsx)(n.code,{children:"ls"})," or ",(0,t.jsx)(n.code,{children:"cat"}),")."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "oclif": {\n "commands": {\n "strategy": "single",\n "target": "./dist/index.js"\n }\n }\n}\n'})}),"\n",(0,t.jsxs)(n.p,{children:["In this example, ",(0,t.jsx)(n.code,{children:"./dist/index.js"})," exports the command class."]}),"\n",(0,t.jsxs)(n.h3,{id:"note-about-oclifmanifestjson",children:["Note about ",(0,t.jsx)(n.code,{children:"oclif.manifest.json"})]}),"\n",(0,t.jsxs)(n.p,{children:["For all strategies, the ",(0,t.jsx)(n.code,{children:"oclif.manifest.json"})," will be used to load the commands instead of the default behavior of the strategy."]})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(r,{...e})}):r(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>l,x:()=>d});var t=s(6540);const o={},i=t.createContext(o);function l(e){const n=t.useContext(i);return t.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function d(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:l(e.components),t.createElement(i.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/32060389.cc2c1970.js b/assets/js/32060389.35ead119.js
similarity index 99%
rename from assets/js/32060389.cc2c1970.js
rename to assets/js/32060389.35ead119.js
index bcb977ab..a19a4aa8 100644
--- a/assets/js/32060389.cc2c1970.js
+++ b/assets/js/32060389.35ead119.js
@@ -1 +1 @@
-"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[7996],{1916:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>l,contentTitle:()=>r,default:()=>u,frontMatter:()=>o,metadata:()=>i,toc:()=>c});var t=s(4848),a=s(8453);const o={title:"Table"},r=void 0,i={id:"table",title:"Table",description:"ux.table",source:"@site/../docs/table.md",sourceDirName:".",slug:"/table",permalink:"/docs/table",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/table.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711121897,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Table"},sidebar:"docs",previous:{title:"Spinner",permalink:"/docs/spinner"},next:{title:"Notifications",permalink:"/docs/notifications"}},l={},c=[{value:"ux.table",id:"uxtable",level:2}];function d(e){const n={a:"a",code:"code",h2:"h2",li:"li",p:"p",pre:"pre",ul:"ul",...(0,a.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.h2,{id:"uxtable",children:(0,t.jsx)(n.code,{children:"ux.table"})}),"\n",(0,t.jsx)(n.p,{children:"Displays tabular data"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"ux.table(data, columns, options)\n"})}),"\n",(0,t.jsx)(n.p,{children:"Where:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"data"}),": array of data objects to display"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"columns"}),": ",(0,t.jsx)(n.a,{href:"https://github.com/oclif/core/blob/main/src/cli-ux/styled/table.ts",children:"Table.Columns"})]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"options"}),": ",(0,t.jsx)(n.a,{href:"https://github.com/oclif/core/blob/main/src/cli-ux/styled/table.ts",children:"Table.Options"})]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"ux.table.flags()"})," returns an object containing all the table flags to include in your command."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"{\n columns: Flags.string({exclusive: ['additional'], description: 'only show provided columns (comma-seperated)'}),\n sort: Flags.string({description: 'property to sort by (prepend '-' for descending)'}),\n filter: Flags.string({description: 'filter property by partial string matching, ex: name=foo'}),\n csv: Flags.boolean({exclusive: ['no-truncate'], description: 'output is csv format'}),\n extended: Flags.boolean({char: 'x', description: 'show extra columns'}),\n 'no-truncate': Flags.boolean({exclusive: ['csv'], description: 'do not truncate output to fit screen'}),\n 'no-header': Flags.boolean({exclusive: ['csv'], description: 'hide table header from output'}),\n}\n"})}),"\n",(0,t.jsxs)(n.p,{children:["Passing ",(0,t.jsx)(n.code,{children:"{only: ['columns']}"})," or ",(0,t.jsx)(n.code,{children:"{except: ['columns']}"})," as an argument into ",(0,t.jsx)(n.code,{children:"cli.table.flags()"})," will allow/block those flags from the returned object."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"ux.Table.Columns"})," defines the table columns and their display options."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"const columns: ux.Table.Columns = {\n // where `.name` is a property of a data object\n name: {}, // \"Name\" inferred as the column header\n id: {\n header: 'ID', // override column header\n minWidth: '10', // column must display at this width or greater\n extended: true, // only display this column when the --extended flag is present\n get: row => `US-O1-${row.id}`, // custom getter for data row object\n },\n}\n"})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"ux.Table.Options"})," defines the table options, most of which are the parsed flags from the user for display customization, all of which are optional."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"const options: ux.Table.Options = {\n printLine: myLogger, // custom logger\n columns: flags.columns,\n sort: flags.sort,\n filter: flags.filter,\n csv: flags.csv,\n extended: flags.extended,\n 'no-truncate': flags['no-truncate'],\n 'no-header': flags['no-header'],\n}\n"})}),"\n",(0,t.jsx)(n.p,{children:"Example class:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"import {Command, ux} from '@oclif/core'\nimport axios from 'axios'\n\nexport default class Users extends Command {\n static flags = {\n ...ux.table.flags()\n }\n\n async run() {\n const {flags} = await this.parse(Users)\n const {data: users} = await axios.get('https://jsonplaceholder.typicode.com/users')\n\n ux.table(users, {\n name: {\n minWidth: 7,\n },\n company: {\n get: row => row.company && row.company.name\n },\n id: {\n header: 'ID',\n extended: true\n }\n }, {\n printLine: this.log.bind(this),\n ...flags, // parsed flags\n })\n }\n}\n"})}),"\n",(0,t.jsx)(n.p,{children:"Displays:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:'$ example-cli users\nName Company\nLeanne Graham Romaguera-Crona\nErvin Howell Deckow-Crist\nClementine Bauch Romaguera-Jacobson\nPatricia Lebsack Robel-Corkery\nChelsey Dietrich Keebler LLC\nMrs. Dennis Schulist Considine-Lockman\nKurtis Weissnat Johns Group\nNicholas Runolfsdottir V Abernathy Group\nGlenna Reichert Yost and Sons\nClementina DuBuque Hoeger LLC\n\n$ example-cli users --extended\nName Company ID\nLeanne Graham Romaguera-Crona 1\nErvin Howell Deckow-Crist 2\nClementine Bauch Romaguera-Jacobson 3\nPatricia Lebsack Robel-Corkery 4\nChelsey Dietrich Keebler LLC 5\nMrs. Dennis Schulist Considine-Lockman 6\nKurtis Weissnat Johns Group 7\nNicholas Runolfsdottir V Abernathy Group 8\nGlenna Reichert Yost and Sons 9\nClementina DuBuque Hoeger LLC 10\n\n$ example-cli users --columns=name\nName\nLeanne Graham\nErvin Howell\nClementine Bauch\nPatricia Lebsack\nChelsey Dietrich\nMrs. Dennis Schulist\nKurtis Weissnat\nNicholas Runolfsdottir V\nGlenna Reichert\nClementina DuBuque\n\n$ example-cli users --filter="company=Group"\nName Company\nKurtis Weissnat Johns Group\nNicholas Runolfsdottir V Abernathy Group\n\n$ example-cli users --sort=company\nName Company\nNicholas Runolfsdottir V Abernathy Group\nMrs. Dennis Schulist Considine-Lockman\nErvin Howell Deckow-Crist\nClementina DuBuque Hoeger LLC\nKurtis Weissnat Johns Group\nChelsey Dietrich Keebler LLC\nPatricia Lebsack Robel-Corkery\nLeanne Graham Romaguera-Crona\nClementine Bauch Romaguera-Jacobson\nGlenna Reichert Yost and Sons\n'})})]})}function u(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>r,x:()=>i});var t=s(6540);const a={},o=t.createContext(a);function r(e){const n=t.useContext(o);return t.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function i(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:r(e.components),t.createElement(o.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
+"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[7996],{1916:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>l,contentTitle:()=>r,default:()=>u,frontMatter:()=>o,metadata:()=>i,toc:()=>c});var t=s(4848),a=s(8453);const o={title:"Table"},r=void 0,i={id:"table",title:"Table",description:"ux.table",source:"@site/../docs/table.md",sourceDirName:".",slug:"/table",permalink:"/docs/table",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/table.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711137687,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Table"},sidebar:"docs",previous:{title:"Spinner",permalink:"/docs/spinner"},next:{title:"Notifications",permalink:"/docs/notifications"}},l={},c=[{value:"ux.table",id:"uxtable",level:2}];function d(e){const n={a:"a",code:"code",h2:"h2",li:"li",p:"p",pre:"pre",ul:"ul",...(0,a.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.h2,{id:"uxtable",children:(0,t.jsx)(n.code,{children:"ux.table"})}),"\n",(0,t.jsx)(n.p,{children:"Displays tabular data"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"ux.table(data, columns, options)\n"})}),"\n",(0,t.jsx)(n.p,{children:"Where:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"data"}),": array of data objects to display"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"columns"}),": ",(0,t.jsx)(n.a,{href:"https://github.com/oclif/core/blob/main/src/cli-ux/styled/table.ts",children:"Table.Columns"})]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"options"}),": ",(0,t.jsx)(n.a,{href:"https://github.com/oclif/core/blob/main/src/cli-ux/styled/table.ts",children:"Table.Options"})]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"ux.table.flags()"})," returns an object containing all the table flags to include in your command."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"{\n columns: Flags.string({exclusive: ['additional'], description: 'only show provided columns (comma-seperated)'}),\n sort: Flags.string({description: 'property to sort by (prepend '-' for descending)'}),\n filter: Flags.string({description: 'filter property by partial string matching, ex: name=foo'}),\n csv: Flags.boolean({exclusive: ['no-truncate'], description: 'output is csv format'}),\n extended: Flags.boolean({char: 'x', description: 'show extra columns'}),\n 'no-truncate': Flags.boolean({exclusive: ['csv'], description: 'do not truncate output to fit screen'}),\n 'no-header': Flags.boolean({exclusive: ['csv'], description: 'hide table header from output'}),\n}\n"})}),"\n",(0,t.jsxs)(n.p,{children:["Passing ",(0,t.jsx)(n.code,{children:"{only: ['columns']}"})," or ",(0,t.jsx)(n.code,{children:"{except: ['columns']}"})," as an argument into ",(0,t.jsx)(n.code,{children:"cli.table.flags()"})," will allow/block those flags from the returned object."]}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"ux.Table.Columns"})," defines the table columns and their display options."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"const columns: ux.Table.Columns = {\n // where `.name` is a property of a data object\n name: {}, // \"Name\" inferred as the column header\n id: {\n header: 'ID', // override column header\n minWidth: '10', // column must display at this width or greater\n extended: true, // only display this column when the --extended flag is present\n get: row => `US-O1-${row.id}`, // custom getter for data row object\n },\n}\n"})}),"\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"ux.Table.Options"})," defines the table options, most of which are the parsed flags from the user for display customization, all of which are optional."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"const options: ux.Table.Options = {\n printLine: myLogger, // custom logger\n columns: flags.columns,\n sort: flags.sort,\n filter: flags.filter,\n csv: flags.csv,\n extended: flags.extended,\n 'no-truncate': flags['no-truncate'],\n 'no-header': flags['no-header'],\n}\n"})}),"\n",(0,t.jsx)(n.p,{children:"Example class:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"import {Command, ux} from '@oclif/core'\nimport axios from 'axios'\n\nexport default class Users extends Command {\n static flags = {\n ...ux.table.flags()\n }\n\n async run() {\n const {flags} = await this.parse(Users)\n const {data: users} = await axios.get('https://jsonplaceholder.typicode.com/users')\n\n ux.table(users, {\n name: {\n minWidth: 7,\n },\n company: {\n get: row => row.company && row.company.name\n },\n id: {\n header: 'ID',\n extended: true\n }\n }, {\n printLine: this.log.bind(this),\n ...flags, // parsed flags\n })\n }\n}\n"})}),"\n",(0,t.jsx)(n.p,{children:"Displays:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-shell",children:'$ example-cli users\nName Company\nLeanne Graham Romaguera-Crona\nErvin Howell Deckow-Crist\nClementine Bauch Romaguera-Jacobson\nPatricia Lebsack Robel-Corkery\nChelsey Dietrich Keebler LLC\nMrs. Dennis Schulist Considine-Lockman\nKurtis Weissnat Johns Group\nNicholas Runolfsdottir V Abernathy Group\nGlenna Reichert Yost and Sons\nClementina DuBuque Hoeger LLC\n\n$ example-cli users --extended\nName Company ID\nLeanne Graham Romaguera-Crona 1\nErvin Howell Deckow-Crist 2\nClementine Bauch Romaguera-Jacobson 3\nPatricia Lebsack Robel-Corkery 4\nChelsey Dietrich Keebler LLC 5\nMrs. Dennis Schulist Considine-Lockman 6\nKurtis Weissnat Johns Group 7\nNicholas Runolfsdottir V Abernathy Group 8\nGlenna Reichert Yost and Sons 9\nClementina DuBuque Hoeger LLC 10\n\n$ example-cli users --columns=name\nName\nLeanne Graham\nErvin Howell\nClementine Bauch\nPatricia Lebsack\nChelsey Dietrich\nMrs. Dennis Schulist\nKurtis Weissnat\nNicholas Runolfsdottir V\nGlenna Reichert\nClementina DuBuque\n\n$ example-cli users --filter="company=Group"\nName Company\nKurtis Weissnat Johns Group\nNicholas Runolfsdottir V Abernathy Group\n\n$ example-cli users --sort=company\nName Company\nNicholas Runolfsdottir V Abernathy Group\nMrs. Dennis Schulist Considine-Lockman\nErvin Howell Deckow-Crist\nClementina DuBuque Hoeger LLC\nKurtis Weissnat Johns Group\nChelsey Dietrich Keebler LLC\nPatricia Lebsack Robel-Corkery\nLeanne Graham Romaguera-Crona\nClementine Bauch Romaguera-Jacobson\nGlenna Reichert Yost and Sons\n'})})]})}function u(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},8453:(e,n,s)=>{s.d(n,{R:()=>r,x:()=>i});var t=s(6540);const a={},o=t.createContext(a);function r(e){const n=t.useContext(o);return t.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function i(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:r(e.components),t.createElement(o.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/35586d92.a74fcd5f.js b/assets/js/35586d92.e8f3fe50.js
similarity index 98%
rename from assets/js/35586d92.a74fcd5f.js
rename to assets/js/35586d92.e8f3fe50.js
index e9ae9664..dc944b5d 100644
--- a/assets/js/35586d92.a74fcd5f.js
+++ b/assets/js/35586d92.e8f3fe50.js
@@ -1 +1 @@
-"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[7187],{1810:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>a,contentTitle:()=>l,default:()=>u,frontMatter:()=>s,metadata:()=>r,toc:()=>d});var o=i(4848),t=i(8453);const s={title:"Plugin Loading"},l=void 0,r={id:"plugin_loading",title:"Plugin Loading",description:"Below is a diagram that outlines how a plugin is loaded into the CLI.",source:"@site/../docs/plugin_loading.md",sourceDirName:".",slug:"/plugin_loading",permalink:"/docs/plugin_loading",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/plugin_loading.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711121897,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Plugin Loading"},sidebar:"docs",previous:{title:"Command Execution",permalink:"/docs/command_execution"},next:{title:"Command Discovery Strategies",permalink:"/docs/command_discovery_strategies"}},a={},d=[{value:"Plugin Resolution Order",id:"plugin-resolution-order",level:3},{value:"Manifests Improve Performance",id:"manifests-improve-performance",level:3},{value:"Plugin Loading Diagram",id:"plugin-loading-diagram",level:2}];function c(e){const n={code:"code",h2:"h2",h3:"h3",img:"img",li:"li",ol:"ol",p:"p",...(0,t.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.p,{children:"Below is a diagram that outlines how a plugin is loaded into the CLI."}),"\n",(0,o.jsx)(n.p,{children:"There are a couple of important takeaways from this diagram:"}),"\n",(0,o.jsx)(n.h3,{id:"plugin-resolution-order",children:"Plugin Resolution Order"}),"\n",(0,o.jsx)(n.p,{children:"Plugins are resolved in the following order:"}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsx)(n.li,{children:"User plugins (i.e. plugins installed by the users)"}),"\n",(0,o.jsxs)(n.li,{children:["Dev plugins (i.e. plugins listed under ",(0,o.jsx)(n.code,{children:"devPlugins"}),")"]}),"\n",(0,o.jsxs)(n.li,{children:["Core plugins (i.e. plugins listed under ",(0,o.jsx)(n.code,{children:"plugins"}),")"]}),"\n"]}),"\n",(0,o.jsx)(n.h3,{id:"manifests-improve-performance",children:"Manifests Improve Performance"}),"\n",(0,o.jsxs)(n.p,{children:["When loading a plugin, oclif needs to require each command file in order to get the static properties of the command - the ",(0,o.jsx)(n.code,{children:"description"}),", ",(0,o.jsx)(n.code,{children:"examples"}),", ",(0,o.jsx)(n.code,{children:"flags"}),", etc..."]}),"\n",(0,o.jsxs)(n.p,{children:["However, oclif can skip this step if the plugin has an ",(0,o.jsx)(n.code,{children:"oclif.manifest.json"})," (generated by ",(0,o.jsx)(n.code,{children:"oclif manifest"}),"). The manifest caches all of these properties so that there's no need to require every single command on every command execution."]}),"\n",(0,o.jsx)(n.h2,{id:"plugin-loading-diagram",children:"Plugin Loading Diagram"}),"\n",(0,o.jsx)(n.p,{children:(0,o.jsx)(n.img,{alt:"plugin loading",src:i(4893).A+"",width:"8787",height:"5576"})})]})}function u(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(c,{...e})}):c(e)}},4893:(e,n,i)=>{i.d(n,{A:()=>o});const o=i.p+"assets/images/plugin-loading-63d248baba4db7ba0a9340ef6b0c0856.jpg"},8453:(e,n,i)=>{i.d(n,{R:()=>l,x:()=>r});var o=i(6540);const t={},s=o.createContext(t);function l(e){const n=o.useContext(s);return o.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:l(e.components),o.createElement(s.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
+"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[7187],{1810:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>a,contentTitle:()=>l,default:()=>u,frontMatter:()=>s,metadata:()=>r,toc:()=>d});var o=i(4848),t=i(8453);const s={title:"Plugin Loading"},l=void 0,r={id:"plugin_loading",title:"Plugin Loading",description:"Below is a diagram that outlines how a plugin is loaded into the CLI.",source:"@site/../docs/plugin_loading.md",sourceDirName:".",slug:"/plugin_loading",permalink:"/docs/plugin_loading",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/plugin_loading.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711137687,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Plugin Loading"},sidebar:"docs",previous:{title:"Command Execution",permalink:"/docs/command_execution"},next:{title:"Command Discovery Strategies",permalink:"/docs/command_discovery_strategies"}},a={},d=[{value:"Plugin Resolution Order",id:"plugin-resolution-order",level:3},{value:"Manifests Improve Performance",id:"manifests-improve-performance",level:3},{value:"Plugin Loading Diagram",id:"plugin-loading-diagram",level:2}];function c(e){const n={code:"code",h2:"h2",h3:"h3",img:"img",li:"li",ol:"ol",p:"p",...(0,t.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.p,{children:"Below is a diagram that outlines how a plugin is loaded into the CLI."}),"\n",(0,o.jsx)(n.p,{children:"There are a couple of important takeaways from this diagram:"}),"\n",(0,o.jsx)(n.h3,{id:"plugin-resolution-order",children:"Plugin Resolution Order"}),"\n",(0,o.jsx)(n.p,{children:"Plugins are resolved in the following order:"}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsx)(n.li,{children:"User plugins (i.e. plugins installed by the users)"}),"\n",(0,o.jsxs)(n.li,{children:["Dev plugins (i.e. plugins listed under ",(0,o.jsx)(n.code,{children:"devPlugins"}),")"]}),"\n",(0,o.jsxs)(n.li,{children:["Core plugins (i.e. plugins listed under ",(0,o.jsx)(n.code,{children:"plugins"}),")"]}),"\n"]}),"\n",(0,o.jsx)(n.h3,{id:"manifests-improve-performance",children:"Manifests Improve Performance"}),"\n",(0,o.jsxs)(n.p,{children:["When loading a plugin, oclif needs to require each command file in order to get the static properties of the command - the ",(0,o.jsx)(n.code,{children:"description"}),", ",(0,o.jsx)(n.code,{children:"examples"}),", ",(0,o.jsx)(n.code,{children:"flags"}),", etc..."]}),"\n",(0,o.jsxs)(n.p,{children:["However, oclif can skip this step if the plugin has an ",(0,o.jsx)(n.code,{children:"oclif.manifest.json"})," (generated by ",(0,o.jsx)(n.code,{children:"oclif manifest"}),"). The manifest caches all of these properties so that there's no need to require every single command on every command execution."]}),"\n",(0,o.jsx)(n.h2,{id:"plugin-loading-diagram",children:"Plugin Loading Diagram"}),"\n",(0,o.jsx)(n.p,{children:(0,o.jsx)(n.img,{alt:"plugin loading",src:i(4893).A+"",width:"8787",height:"5576"})})]})}function u(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(c,{...e})}):c(e)}},4893:(e,n,i)=>{i.d(n,{A:()=>o});const o=i.p+"assets/images/plugin-loading-63d248baba4db7ba0a9340ef6b0c0856.jpg"},8453:(e,n,i)=>{i.d(n,{R:()=>l,x:()=>r});var o=i(6540);const t={},s=o.createContext(t);function l(e){const n=o.useContext(s);return o.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:l(e.components),o.createElement(s.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/3e452c7e.747c7b5b.js b/assets/js/3e452c7e.815db200.js
similarity index 98%
rename from assets/js/3e452c7e.747c7b5b.js
rename to assets/js/3e452c7e.815db200.js
index 3cfe40cd..3bc08420 100644
--- a/assets/js/3e452c7e.747c7b5b.js
+++ b/assets/js/3e452c7e.815db200.js
@@ -1 +1 @@
-"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[55],{7780:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>l,contentTitle:()=>r,default:()=>d,frontMatter:()=>o,metadata:()=>c,toc:()=>i});var a=s(4848),t=s(8453);const o={title:"Custom Base Class"},r=void 0,c={id:"base_class",title:"Custom Base Class",description:"Use inheritance to share functionality between common commands. Here is an example of a command base class that has some common shared flags.",source:"@site/../docs/base_class.md",sourceDirName:".",slug:"/base_class",permalink:"/docs/base_class",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/base_class.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711121897,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Custom Base Class"},sidebar:"docs",previous:{title:"NSIS Installer Customization",permalink:"/docs/nsis-installer_customization"},next:{title:"Prompting",permalink:"/docs/prompting"}},l={},i=[];function m(e){const n={a:"a",code:"code",p:"p",pre:"pre",...(0,t.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(n.p,{children:"Use inheritance to share functionality between common commands. Here is an example of a command base class that has some common shared flags."}),"\n",(0,a.jsx)(n.p,{children:"For large CLIs with multiple plugins, it's useful to put this base class into its own npm package to be shared."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-typescript",children:"// src/baseCommand.ts\nimport {Command, Flags, Interfaces} from '@oclif/core'\n\nenum LogLevel {\n debug = 'debug',\n info = 'info',\n warn = 'warn',\n error = 'error',\n}\n\nexport type Flagsthis.log(message: string)",id:"thislogmessage-string",level:3},{value:"this.warn(message: string | Error)",id:"thiswarnmessage-string--error",level:3},{value:"this.error(message: string | Error, options?: {code?: string, exit?: number, ref?: string; suggestions?: string[];})",id:"thiserrormessage-string--error-options-code-string-exit-number-ref-string-suggestions-string",level:3},{value:"this.exit(code: number = 0)",id:"thisexitcode-number--0",level:3},{value:"this.logToStderr(message: string)",id:"thislogtostderrmessage-string",level:3},{value:"this.jsonEnabled()",id:"thisjsonenabled",level:3},{value:"this.toSuccessJson(result: unknown)",id:"thistosuccessjsonresult-unknown",level:3},{value:"this.toErrorJson(result: unknown)",id:"thistoerrorjsonresult-unknown",level:3}];function l(e){const n={a:"a",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.p,{children:"A basic command looks like the following in TypeScript:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-js",children:"import {Command} from '@oclif/core'\n\nexport class MyCommand extends Command {\n static description = 'description of this example command'\n\n async run(): Promisethis.log(message: string)",id:"thislogmessage-string",level:3},{value:"this.warn(message: string | Error)",id:"thiswarnmessage-string--error",level:3},{value:"this.error(message: string | Error, options?: {code?: string, exit?: number, ref?: string; suggestions?: string[];})",id:"thiserrormessage-string--error-options-code-string-exit-number-ref-string-suggestions-string",level:3},{value:"this.exit(code: number = 0)",id:"thisexitcode-number--0",level:3},{value:"this.logToStderr(message: string)",id:"thislogtostderrmessage-string",level:3},{value:"this.jsonEnabled()",id:"thisjsonenabled",level:3},{value:"this.toSuccessJson(result: unknown)",id:"thistosuccessjsonresult-unknown",level:3},{value:"this.toErrorJson(result: unknown)",id:"thistoerrorjsonresult-unknown",level:3}];function l(e){const n={a:"a",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.p,{children:"A basic command looks like the following in TypeScript:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-js",children:"import {Command} from '@oclif/core'\n\nexport class MyCommand extends Command {\n static description = 'description of this example command'\n\n async run(): Promiseux.prompt()",id:"uxprompt",level:2},{value:"inquirer",id:"inquirer",level:2}];function d(e){const n={a:"a",code:"code",h2:"h2",img:"img",p:"p",pre:"pre",strong:"strong",...(0,r.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.a,{href:"https://github.com/oclif/core/blob/main/src/cli-ux/README.md",children:"ux"})," export provides a simple ",(0,s.jsx)(n.code,{children:"cli.prompt()"})," function, for more complex input prompts, we recommend using the ",(0,s.jsx)(n.a,{href:"https://github.com/SBoudrias/Inquirer.js",children:"inquirer"})," library."]}),"\n",(0,s.jsx)(n.h2,{id:"uxprompt",children:(0,s.jsx)(n.code,{children:"ux.prompt()"})}),"\n",(0,s.jsxs)(n.p,{children:["Prompt for basic input with ",(0,s.jsx)(n.code,{children:"ux"}),":"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-typescript",children:"import {Command, ux} from '@oclif/core'\n\nexport class MyCommand extends Command {\n async run() {\n // just prompt for input\n const name = await ux.prompt('What is your name?')\n\n // mask input after enter is pressed\n const secondFactor = await ux.prompt('What is your two-factor token?', {type: 'mask'})\n\n // hide input while typing\n const password = await ux.prompt('What is your password?', {type: 'hide'})\n\n this.log(`You entered: ${name}, ${secondFactor}, ${password}`)\n }\n}\n"})}),"\n",(0,s.jsx)(n.p,{children:"Demo:"}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.img,{alt:"prompt demo",src:t(164).A+"",width:"941",height:"605"})}),"\n",(0,s.jsx)(n.h2,{id:"inquirer",children:(0,s.jsx)(n.code,{children:"inquirer"})}),"\n",(0,s.jsxs)(n.p,{children:["Here is an example command that uses ",(0,s.jsx)(n.a,{href:"https://github.com/SBoudrias/Inquirer.js",children:"inquirer"}),". You will need to add ",(0,s.jsx)(n.code,{children:"inquirer"})," and ",(0,s.jsx)(n.code,{children:"@types/inquirer"})," (for TypeScript CLIs) for this to work."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-typescript",children:"import {Command, Flags} from '@oclif/core'\nimport * as inquirer from 'inquirer'\n\nexport class MyCommand extends Command {\n static flags = {\n stage: Flags.string({options: ['development', 'staging', 'production']})\n }\n\n async run() {\n const {flags} = await this.parse(MyCommand)\n let stage = flags.stage\n if (!stage) {\n let responses: any = await inquirer.prompt([{\n name: 'stage',\n message: 'select a stage',\n type: 'list',\n choices: [{name: 'development'}, {name: 'staging'}, {name: 'production'}],\n }])\n stage = responses.stage\n }\n this.log(`the stage is: ${stage}`)\n }\n}\n"})}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"NOTE"}),": inquirer >= v9 is an ESM package. If you aren't using ESM in your CLI/plugin, you should set ",(0,s.jsxs)(n.a,{href:"https://www.typescriptlang.org/tsconfig#moduleResolution",children:[(0,s.jsx)(n.code,{children:"moduleResolution"})," to ",(0,s.jsx)(n.code,{children:"node16"})]})," in your tsconfig.json and ",(0,s.jsxs)(n.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import",children:["import it using ",(0,s.jsx)(n.code,{children:"await import"})]}),":"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-typescript",children:"import {Command, Flags} from '@oclif/core'\n\nexport class MyCommand extends Command {\n static flags = {\n stage: Flags.string({options: ['development', 'staging', 'production']})\n }\n\n async run() {\n const {flags} = await this.parse(MyCommand)\n let stage = flags.stage\n if (!stage) {\n const { default: inquirer } = await import(\"inquirer\")\n let responses: any = inquirer.prompt([{\n name: 'stage',\n message: 'select a stage',\n type: 'list',\n choices: [{name: 'development'}, {name: 'staging'}, {name: 'production'}],\n }])\n stage = responses.stage\n }\n this.log(`the stage is: ${stage}`)\n }\n}\n"})}),"\n",(0,s.jsx)(n.p,{children:"Demo:"}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.img,{alt:"inquirer demo",src:t(7915).A+"",width:"1254",height:"806"})})]})}function m(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},7915:(e,n,t)=>{t.d(n,{A:()=>s});const s=t.p+"assets/images/inquirer_demo-4d4cd8f9cf0bf300a5b853a4beef5672.gif"},164:(e,n,t)=>{t.d(n,{A:()=>s});const s=t.p+"assets/images/prompt_demo-7bc9d5f614fdad73636bec3c864aff15.gif"},8453:(e,n,t)=>{t.d(n,{R:()=>i,x:()=>a});var s=t(6540);const r={},o=s.createContext(r);function i(e){const n=s.useContext(o);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:i(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
+"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[7071],{6362:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>i,default:()=>m,frontMatter:()=>o,metadata:()=>a,toc:()=>p});var s=t(4848),r=t(8453);const o={title:"Prompting"},i=void 0,a={id:"prompting",title:"Prompting",description:"The ux export provides a simple cli.prompt() function, for more complex input prompts, we recommend using the inquirer library.",source:"@site/../docs/prompting.md",sourceDirName:".",slug:"/prompting",permalink:"/docs/prompting",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/prompting.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711137687,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Prompting"},sidebar:"docs",previous:{title:"Custom Base Class",permalink:"/docs/base_class"},next:{title:"Spinner",permalink:"/docs/spinner"}},c={},p=[{value:"ux.prompt()",id:"uxprompt",level:2},{value:"inquirer",id:"inquirer",level:2}];function d(e){const n={a:"a",code:"code",h2:"h2",img:"img",p:"p",pre:"pre",strong:"strong",...(0,r.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.a,{href:"https://github.com/oclif/core/blob/main/src/cli-ux/README.md",children:"ux"})," export provides a simple ",(0,s.jsx)(n.code,{children:"cli.prompt()"})," function, for more complex input prompts, we recommend using the ",(0,s.jsx)(n.a,{href:"https://github.com/SBoudrias/Inquirer.js",children:"inquirer"})," library."]}),"\n",(0,s.jsx)(n.h2,{id:"uxprompt",children:(0,s.jsx)(n.code,{children:"ux.prompt()"})}),"\n",(0,s.jsxs)(n.p,{children:["Prompt for basic input with ",(0,s.jsx)(n.code,{children:"ux"}),":"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-typescript",children:"import {Command, ux} from '@oclif/core'\n\nexport class MyCommand extends Command {\n async run() {\n // just prompt for input\n const name = await ux.prompt('What is your name?')\n\n // mask input after enter is pressed\n const secondFactor = await ux.prompt('What is your two-factor token?', {type: 'mask'})\n\n // hide input while typing\n const password = await ux.prompt('What is your password?', {type: 'hide'})\n\n this.log(`You entered: ${name}, ${secondFactor}, ${password}`)\n }\n}\n"})}),"\n",(0,s.jsx)(n.p,{children:"Demo:"}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.img,{alt:"prompt demo",src:t(164).A+"",width:"941",height:"605"})}),"\n",(0,s.jsx)(n.h2,{id:"inquirer",children:(0,s.jsx)(n.code,{children:"inquirer"})}),"\n",(0,s.jsxs)(n.p,{children:["Here is an example command that uses ",(0,s.jsx)(n.a,{href:"https://github.com/SBoudrias/Inquirer.js",children:"inquirer"}),". You will need to add ",(0,s.jsx)(n.code,{children:"inquirer"})," and ",(0,s.jsx)(n.code,{children:"@types/inquirer"})," (for TypeScript CLIs) for this to work."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-typescript",children:"import {Command, Flags} from '@oclif/core'\nimport * as inquirer from 'inquirer'\n\nexport class MyCommand extends Command {\n static flags = {\n stage: Flags.string({options: ['development', 'staging', 'production']})\n }\n\n async run() {\n const {flags} = await this.parse(MyCommand)\n let stage = flags.stage\n if (!stage) {\n let responses: any = await inquirer.prompt([{\n name: 'stage',\n message: 'select a stage',\n type: 'list',\n choices: [{name: 'development'}, {name: 'staging'}, {name: 'production'}],\n }])\n stage = responses.stage\n }\n this.log(`the stage is: ${stage}`)\n }\n}\n"})}),"\n",(0,s.jsxs)(n.p,{children:[(0,s.jsx)(n.strong,{children:"NOTE"}),": inquirer >= v9 is an ESM package. If you aren't using ESM in your CLI/plugin, you should set ",(0,s.jsxs)(n.a,{href:"https://www.typescriptlang.org/tsconfig#moduleResolution",children:[(0,s.jsx)(n.code,{children:"moduleResolution"})," to ",(0,s.jsx)(n.code,{children:"node16"})]})," in your tsconfig.json and ",(0,s.jsxs)(n.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import",children:["import it using ",(0,s.jsx)(n.code,{children:"await import"})]}),":"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-typescript",children:"import {Command, Flags} from '@oclif/core'\n\nexport class MyCommand extends Command {\n static flags = {\n stage: Flags.string({options: ['development', 'staging', 'production']})\n }\n\n async run() {\n const {flags} = await this.parse(MyCommand)\n let stage = flags.stage\n if (!stage) {\n const { default: inquirer } = await import(\"inquirer\")\n let responses: any = inquirer.prompt([{\n name: 'stage',\n message: 'select a stage',\n type: 'list',\n choices: [{name: 'development'}, {name: 'staging'}, {name: 'production'}],\n }])\n stage = responses.stage\n }\n this.log(`the stage is: ${stage}`)\n }\n}\n"})}),"\n",(0,s.jsx)(n.p,{children:"Demo:"}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.img,{alt:"inquirer demo",src:t(7915).A+"",width:"1254",height:"806"})})]})}function m(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},7915:(e,n,t)=>{t.d(n,{A:()=>s});const s=t.p+"assets/images/inquirer_demo-4d4cd8f9cf0bf300a5b853a4beef5672.gif"},164:(e,n,t)=>{t.d(n,{A:()=>s});const s=t.p+"assets/images/prompt_demo-7bc9d5f614fdad73636bec3c864aff15.gif"},8453:(e,n,t)=>{t.d(n,{R:()=>i,x:()=>a});var s=t(6540);const r={},o=s.createContext(r);function i(e){const n=s.useContext(o);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:i(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/82247a8b.de433149.js b/assets/js/82247a8b.6dd022f7.js
similarity index 99%
rename from assets/js/82247a8b.de433149.js
rename to assets/js/82247a8b.6dd022f7.js
index bad26fa9..aa5726c9 100644
--- a/assets/js/82247a8b.de433149.js
+++ b/assets/js/82247a8b.6dd022f7.js
@@ -1 +1 @@
-"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[9409],{7840:(n,e,s)=>{s.r(e),s.d(e,{assets:()=>l,contentTitle:()=>c,default:()=>h,frontMatter:()=>o,metadata:()=>t,toc:()=>d});var i=s(4848),r=s(8453);const o={title:"Configuration"},c=void 0,t={id:"config",title:"Configuration",description:"Inside a command, this.config provides useful properties you can use in your command. Here are a list of its methods and properties:",source:"@site/../docs/config.md",sourceDirName:".",slug:"/config",permalink:"/docs/config",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/config.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711121897,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Configuration"},sidebar:"docs",previous:{title:"Command Flags",permalink:"/docs/flags"},next:{title:"Topics",permalink:"/docs/topics"}},l={},d=[{value:"Custom User Configuration",id:"custom-user-configuration",level:2}];function a(n){const e={a:"a",code:"code",h2:"h2",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...n.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsxs)(e.p,{children:["Inside a command, ",(0,i.jsx)(e.code,{children:"this.config"})," provides useful properties you can use in your command. Here are a list of its methods and properties:"]}),"\n",(0,i.jsxs)(e.ul,{children:["\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"name"})," - name of CLI"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"version"})," - Version of the CLI."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"pjson"})," - Parsed and ",(0,i.jsx)(e.a,{href:"https://github.com/npm/normalize-package-data",children:"normalized"})," CLI ",(0,i.jsx)(e.code,{children:"package.json"}),"."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"bin"})," - CLI bin name"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"binAliases"})," - An array of strings that will all execute the CLI's bin. This is useful for backwards compatibility and for CLIs built with installers or tarballs. For npm-installed CLIs, change the ",(0,i.jsx)(e.code,{children:"bin"})," property in ",(0,i.jsx)(e.code,{children:"package.json"})," instead. See ",(0,i.jsx)(e.a,{href:"https://oclif.io/docs/aliases",children:"Bin Aliases"})," for more information."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"nsisCustomization"})," - A path to a .nsis file that's used to customize the installer for Windows. See ",(0,i.jsx)(e.a,{href:"https://github.com/oclif/nsis-custom",children:"nsis-custom"})," for more information."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"cacheDir"})," - CLI cache directory","\n",(0,i.jsxs)(e.ul,{children:["\n",(0,i.jsxs)(e.li,{children:["macOS: ",(0,i.jsx)(e.code,{children:"~/Library/Caches/mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Unix: ",(0,i.jsx)(e.code,{children:"~/.cache/mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Windows: ",(0,i.jsx)(e.code,{children:"%LOCALAPPDATA%\\mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Can be overridden with ",(0,i.jsx)(e.code,{children:"XDG_CACHE_HOME"})]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"configDir"})," - CLI config directory","\n",(0,i.jsxs)(e.ul,{children:["\n",(0,i.jsxs)(e.li,{children:["Unix: ",(0,i.jsx)(e.code,{children:"~/.config/mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Windows: ",(0,i.jsx)(e.code,{children:"%LOCALAPPDATA%\\mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Can be overridden with ",(0,i.jsx)(e.code,{children:"XDG_CONFIG_HOME"})]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"dataDir"})," - CLI data directory","\n",(0,i.jsxs)(e.ul,{children:["\n",(0,i.jsxs)(e.li,{children:["Unix: ",(0,i.jsx)(e.code,{children:"~/.data/mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Windows: ",(0,i.jsx)(e.code,{children:"%LOCALAPPDATA%\\mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Can be overridden with ",(0,i.jsx)(e.code,{children:"XDG_DATA_HOME"})]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"dirname"})," - dirname used with ",(0,i.jsx)(e.code,{children:"cacheDir|configDir|dataDir"}),". Can be overridden in ",(0,i.jsx)(e.code,{children:"package.json"}),"."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"errlog"})," - path to error log inside of ",(0,i.jsx)(e.code,{children:"cacheDir"})]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"home"})," - user home directory"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"platform"})," - operating system ",(0,i.jsx)(e.code,{children:"darwin|linux|win32"})]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"arch"})," - process architecture ",(0,i.jsx)(e.code,{children:"x64|x86"})]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"shell"})," - current shell in use"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"userAgent"})," - user-agent intended for http calls. example: ",(0,i.jsx)(e.code,{children:"mycli/1.2.3 (darwin-x64) node-9.0.0"})]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"windows"})," - boolean"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"topicSeparator"})," - the separator to use between topics - only colons (",(0,i.jsx)(e.code,{children:'":"'}),") and spaces (",(0,i.jsx)(e.code,{children:'" "'}),") are supported."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"debug"})," - set to 1 if debug is enabled (with ",(0,i.jsx)(e.code,{children:"${BIN}_DEBUG=1"})," or ",(0,i.jsx)(e.code,{children:"DEBUG=$BIN"}),"). In the future this may be used for multiple debug levels."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"npmRegistry"})," - current npm registry to use with the ",(0,i.jsx)(e.a,{href:"https://github.com/oclif/plugin-plugins",children:"plugins"})," plugin"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"plugins"})," - loaded plugins"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"commands"})," - all commands in CLI"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"default"})," - default cli command"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"topics"})," - all topics in CLI"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"commandIDs"})," - string IDs of all commands"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"async runHook(event, opts)"})," - trigger a hook"]}),"\n"]}),"\n",(0,i.jsx)(e.h2,{id:"custom-user-configuration",children:"Custom User Configuration"}),"\n",(0,i.jsxs)(e.p,{children:["Often it's useful to have a custom configuration for your users. One way to implement this is to read a ",(0,i.jsx)(e.code,{children:"config.json"})," file from the CLI's config directory:"]}),"\n",(0,i.jsx)(e.pre,{children:(0,i.jsx)(e.code,{className:"language-typescript",children:"import {Command} from '@oclif/core'\nimport * as fs from 'fs-extra'\nimport * as path from 'path'\n\nexport class extends Command {\n async run() {\n const userConfig = await fs.readJSON(path.join(this.config.configDir, 'config.json'))\n\n this.log('User config:')\n console.dir(userConfig)\n }\n}\n"})}),"\n",(0,i.jsxs)(e.p,{children:["To share this logic between different commands, use a ",(0,i.jsx)(e.a,{href:"/docs/base_class",children:"base class"}),"."]})]})}function h(n={}){const{wrapper:e}={...(0,r.R)(),...n.components};return e?(0,i.jsx)(e,{...n,children:(0,i.jsx)(a,{...n})}):a(n)}},8453:(n,e,s)=>{s.d(e,{R:()=>c,x:()=>t});var i=s(6540);const r={},o=i.createContext(r);function c(n){const e=i.useContext(o);return i.useMemo((function(){return"function"==typeof n?n(e):{...e,...n}}),[e,n])}function t(n){let e;return e=n.disableParentContext?"function"==typeof n.components?n.components(r):n.components||r:c(n.components),i.createElement(o.Provider,{value:e},n.children)}}}]);
\ No newline at end of file
+"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[9409],{7840:(n,e,s)=>{s.r(e),s.d(e,{assets:()=>l,contentTitle:()=>c,default:()=>h,frontMatter:()=>o,metadata:()=>t,toc:()=>d});var i=s(4848),r=s(8453);const o={title:"Configuration"},c=void 0,t={id:"config",title:"Configuration",description:"Inside a command, this.config provides useful properties you can use in your command. Here are a list of its methods and properties:",source:"@site/../docs/config.md",sourceDirName:".",slug:"/config",permalink:"/docs/config",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/config.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711137687,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Configuration"},sidebar:"docs",previous:{title:"Command Flags",permalink:"/docs/flags"},next:{title:"Topics",permalink:"/docs/topics"}},l={},d=[{value:"Custom User Configuration",id:"custom-user-configuration",level:2}];function a(n){const e={a:"a",code:"code",h2:"h2",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...n.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsxs)(e.p,{children:["Inside a command, ",(0,i.jsx)(e.code,{children:"this.config"})," provides useful properties you can use in your command. Here are a list of its methods and properties:"]}),"\n",(0,i.jsxs)(e.ul,{children:["\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"name"})," - name of CLI"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"version"})," - Version of the CLI."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"pjson"})," - Parsed and ",(0,i.jsx)(e.a,{href:"https://github.com/npm/normalize-package-data",children:"normalized"})," CLI ",(0,i.jsx)(e.code,{children:"package.json"}),"."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"bin"})," - CLI bin name"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"binAliases"})," - An array of strings that will all execute the CLI's bin. This is useful for backwards compatibility and for CLIs built with installers or tarballs. For npm-installed CLIs, change the ",(0,i.jsx)(e.code,{children:"bin"})," property in ",(0,i.jsx)(e.code,{children:"package.json"})," instead. See ",(0,i.jsx)(e.a,{href:"https://oclif.io/docs/aliases",children:"Bin Aliases"})," for more information."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"nsisCustomization"})," - A path to a .nsis file that's used to customize the installer for Windows. See ",(0,i.jsx)(e.a,{href:"https://github.com/oclif/nsis-custom",children:"nsis-custom"})," for more information."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"cacheDir"})," - CLI cache directory","\n",(0,i.jsxs)(e.ul,{children:["\n",(0,i.jsxs)(e.li,{children:["macOS: ",(0,i.jsx)(e.code,{children:"~/Library/Caches/mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Unix: ",(0,i.jsx)(e.code,{children:"~/.cache/mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Windows: ",(0,i.jsx)(e.code,{children:"%LOCALAPPDATA%\\mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Can be overridden with ",(0,i.jsx)(e.code,{children:"XDG_CACHE_HOME"})]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"configDir"})," - CLI config directory","\n",(0,i.jsxs)(e.ul,{children:["\n",(0,i.jsxs)(e.li,{children:["Unix: ",(0,i.jsx)(e.code,{children:"~/.config/mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Windows: ",(0,i.jsx)(e.code,{children:"%LOCALAPPDATA%\\mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Can be overridden with ",(0,i.jsx)(e.code,{children:"XDG_CONFIG_HOME"})]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"dataDir"})," - CLI data directory","\n",(0,i.jsxs)(e.ul,{children:["\n",(0,i.jsxs)(e.li,{children:["Unix: ",(0,i.jsx)(e.code,{children:"~/.data/mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Windows: ",(0,i.jsx)(e.code,{children:"%LOCALAPPDATA%\\mycli"})]}),"\n",(0,i.jsxs)(e.li,{children:["Can be overridden with ",(0,i.jsx)(e.code,{children:"XDG_DATA_HOME"})]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"dirname"})," - dirname used with ",(0,i.jsx)(e.code,{children:"cacheDir|configDir|dataDir"}),". Can be overridden in ",(0,i.jsx)(e.code,{children:"package.json"}),"."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"errlog"})," - path to error log inside of ",(0,i.jsx)(e.code,{children:"cacheDir"})]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"home"})," - user home directory"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"platform"})," - operating system ",(0,i.jsx)(e.code,{children:"darwin|linux|win32"})]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"arch"})," - process architecture ",(0,i.jsx)(e.code,{children:"x64|x86"})]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"shell"})," - current shell in use"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"userAgent"})," - user-agent intended for http calls. example: ",(0,i.jsx)(e.code,{children:"mycli/1.2.3 (darwin-x64) node-9.0.0"})]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"windows"})," - boolean"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"topicSeparator"})," - the separator to use between topics - only colons (",(0,i.jsx)(e.code,{children:'":"'}),") and spaces (",(0,i.jsx)(e.code,{children:'" "'}),") are supported."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"debug"})," - set to 1 if debug is enabled (with ",(0,i.jsx)(e.code,{children:"${BIN}_DEBUG=1"})," or ",(0,i.jsx)(e.code,{children:"DEBUG=$BIN"}),"). In the future this may be used for multiple debug levels."]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"npmRegistry"})," - current npm registry to use with the ",(0,i.jsx)(e.a,{href:"https://github.com/oclif/plugin-plugins",children:"plugins"})," plugin"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"plugins"})," - loaded plugins"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"commands"})," - all commands in CLI"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"default"})," - default cli command"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"topics"})," - all topics in CLI"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"commandIDs"})," - string IDs of all commands"]}),"\n",(0,i.jsxs)(e.li,{children:[(0,i.jsx)(e.strong,{children:"async runHook(event, opts)"})," - trigger a hook"]}),"\n"]}),"\n",(0,i.jsx)(e.h2,{id:"custom-user-configuration",children:"Custom User Configuration"}),"\n",(0,i.jsxs)(e.p,{children:["Often it's useful to have a custom configuration for your users. One way to implement this is to read a ",(0,i.jsx)(e.code,{children:"config.json"})," file from the CLI's config directory:"]}),"\n",(0,i.jsx)(e.pre,{children:(0,i.jsx)(e.code,{className:"language-typescript",children:"import {Command} from '@oclif/core'\nimport * as fs from 'fs-extra'\nimport * as path from 'path'\n\nexport class extends Command {\n async run() {\n const userConfig = await fs.readJSON(path.join(this.config.configDir, 'config.json'))\n\n this.log('User config:')\n console.dir(userConfig)\n }\n}\n"})}),"\n",(0,i.jsxs)(e.p,{children:["To share this logic between different commands, use a ",(0,i.jsx)(e.a,{href:"/docs/base_class",children:"base class"}),"."]})]})}function h(n={}){const{wrapper:e}={...(0,r.R)(),...n.components};return e?(0,i.jsx)(e,{...n,children:(0,i.jsx)(a,{...n})}):a(n)}},8453:(n,e,s)=>{s.d(e,{R:()=>c,x:()=>t});var i=s(6540);const r={},o=i.createContext(r);function c(n){const e=i.useContext(o);return i.useMemo((function(){return"function"==typeof n?n(e):{...e,...n}}),[e,n])}function t(n){let e;return e=n.disableParentContext?"function"==typeof n.components?n.components(r):n.components||r:c(n.components),i.createElement(o.Provider,{value:e},n.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/8705a681.eedb41eb.js b/assets/js/8705a681.0456c67d.js
similarity index 99%
rename from assets/js/8705a681.eedb41eb.js
rename to assets/js/8705a681.0456c67d.js
index 51f3b322..68bcd74e 100644
--- a/assets/js/8705a681.eedb41eb.js
+++ b/assets/js/8705a681.0456c67d.js
@@ -1 +1 @@
-"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[125],{1766:(n,e,t)=>{t.r(e),t.d(e,{assets:()=>c,contentTitle:()=>o,default:()=>p,frontMatter:()=>i,metadata:()=>r,toc:()=>l});var a=t(4848),s=t(8453);const i={title:"Running Commands Programmatically"},o=void 0,r={id:"running_programmatically",title:"Running Commands Programmatically",description:"If you need to run a command from another, or programmatically run a command in another codebase, there are a couple options.",source:"@site/../docs/running_programmatically.md",sourceDirName:".",slug:"/running_programmatically",permalink:"/docs/running_programmatically",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/running_programmatically.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711121897,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Running Commands Programmatically"},sidebar:"docs",previous:{title:"Testing",permalink:"/docs/testing"},next:{title:"Just-in-Time Plugin Installation",permalink:"/docs/jit_plugins"}},c={},l=[{value:"Sharing code with modules",id:"sharing-code-with-modules",level:2},{value:"Calling commands directly",id:"calling-commands-directly",level:2}];function d(n){const e={a:"a",code:"code",em:"em",h2:"h2",p:"p",pre:"pre",strong:"strong",...(0,s.R)(),...n.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(e.p,{children:"If you need to run a command from another, or programmatically run a command in another codebase, there are a couple options."}),"\n",(0,a.jsx)(e.p,{children:"First, it is generally a bad idea to run a command directly as the command exports a user interface, not a code interface. It's a design smell that should rarely (if ever) be used. Generally speaking, it's better to break up the code so that it can be called directly rather than as a command. We'll show this better method first."}),"\n",(0,a.jsx)(e.h2,{id:"sharing-code-with-modules",children:"Sharing code with modules"}),"\n",(0,a.jsxs)(e.p,{children:["For example, if we use ",(0,a.jsx)(e.code,{children:"sf config list"})," as an example, we could have a command that outputs the config vars of an app to the screen like this:"]}),"\n",(0,a.jsx)(e.p,{children:(0,a.jsx)(e.strong,{children:"./src/commands/config/list.ts"})}),"\n",(0,a.jsx)(e.pre,{children:(0,a.jsx)(e.code,{className:"language-typescript",children:"export class ConfigList extends Command {\n static flags = {\n app: Flags.string({required: true})\n }\n\n async run() {\n const {flags} = await this.parse(ConfigList)\n const config = await api.get(`/apps/${flags.app}/config-vars`)\n for (let [key, value] of Object.entries(config)) {\n this.log(`${key}=${value}`)\n }\n }\n}\n"})}),"\n",(0,a.jsxs)(e.p,{children:["If we had another command such as ",(0,a.jsx)(e.code,{children:"sf config update"})," that would do some logic then display the config variables using the same logic, we should create a new module that we could call directly:"]}),"\n",(0,a.jsx)(e.p,{children:(0,a.jsx)(e.strong,{children:"./src/commands/config/update.ts"})}),"\n",(0,a.jsx)(e.pre,{children:(0,a.jsx)(e.code,{className:"language-typescript",children:"import {displayConfigVars} from '../displayConfigVars'\n\nexport class ConfigUpdate extends Command {\n static flags = {\n app: Flags.string({required: true})\n }\n\n async run() {\n const {flags} = await this.parse(ConfigUpdate)\n await this.doUpdate(flags.app)\n await displayConfigVars(flags.app)\n }\n}\n"})}),"\n",(0,a.jsx)(e.p,{children:(0,a.jsx)(e.strong,{children:"./src/displayConfigVars.ts"})}),"\n",(0,a.jsx)(e.pre,{children:(0,a.jsx)(e.code,{className:"language-typescript",children:"export async function displayConfigVars(app: string) {\n const config = await api.get(`/apps/${app}config-vars`)\n for (let [key, value] of Object.entries(config)) {\n this.log(`${key}=${value}`)\n }\n}\n"})}),"\n",(0,a.jsx)(e.p,{children:"This is the recommended way to share code. This can be extended further by putting shared code into its own npm package."}),"\n",(0,a.jsx)(e.h2,{id:"calling-commands-directly",children:"Calling commands directly"}),"\n",(0,a.jsxs)(e.p,{children:["Still, if you ",(0,a.jsx)(e.em,{children:"really"})," want to call a command directly, it's easy to do. You have a couple of options."]}),"\n",(0,a.jsxs)(e.p,{children:["If you know that the command you want to run is installed in the CLI, you can use ",(0,a.jsx)(e.code,{children:"this.config.runCommand"}),". For this, we could write our ",(0,a.jsx)(e.code,{children:"sf config update"})," command like so:"]}),"\n",(0,a.jsx)(e.p,{children:(0,a.jsx)(e.strong,{children:"./src/commands/config/update.ts"})}),"\n",(0,a.jsx)(e.pre,{children:(0,a.jsx)(e.code,{className:"language-typescript",children:"export class ConfigUpdate extends Command {\n static flags = {\n app: Flags.string({required: true})\n }\n\n async run() {\n const {flags} = await this.parse(ConfigUpdate)\n await this.doUpdate(flags.app)\n await this.config.runCommand('config:list', ['--global'])\n }\n}\n"})}),"\n",(0,a.jsx)(e.p,{children:"Or you could import the command directly and execute it directly like so:"}),"\n",(0,a.jsx)(e.p,{children:(0,a.jsx)(e.strong,{children:"./src/commands/config/update.ts"})}),"\n",(0,a.jsx)(e.pre,{children:(0,a.jsx)(e.code,{className:"language-typescript",children:"import {ConfigList} from './config/list'\n\nexport class ConfigUpdate extends Command {\n static flags = {\n app: Flags.string({required: true})\n }\n\n async run() {\n const {flags} = await this.parse(ConfigUpdate)\n await this.doUpdate(flags.app)\n await ConfigList.run(['--global'])\n }\n}\n"})}),"\n",(0,a.jsxs)(e.p,{children:["This works because commands have a static ",(0,a.jsx)(e.code,{children:".run()"})," ",(0,a.jsx)(e.a,{href:"https://github.com/oclif/core/blob/main/src/command.ts",children:"method on them"})," that can be used to instantiate the command and run the instance ",(0,a.jsx)(e.code,{children:".run()"})," method. It takes in the argv as input to the command."]})]})}function p(n={}){const{wrapper:e}={...(0,s.R)(),...n.components};return e?(0,a.jsx)(e,{...n,children:(0,a.jsx)(d,{...n})}):d(n)}},8453:(n,e,t)=>{t.d(e,{R:()=>o,x:()=>r});var a=t(6540);const s={},i=a.createContext(s);function o(n){const e=a.useContext(i);return a.useMemo((function(){return"function"==typeof n?n(e):{...e,...n}}),[e,n])}function r(n){let e;return e=n.disableParentContext?"function"==typeof n.components?n.components(s):n.components||s:o(n.components),a.createElement(i.Provider,{value:e},n.children)}}}]);
\ No newline at end of file
+"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[125],{1766:(n,e,t)=>{t.r(e),t.d(e,{assets:()=>c,contentTitle:()=>o,default:()=>p,frontMatter:()=>i,metadata:()=>r,toc:()=>l});var a=t(4848),s=t(8453);const i={title:"Running Commands Programmatically"},o=void 0,r={id:"running_programmatically",title:"Running Commands Programmatically",description:"If you need to run a command from another, or programmatically run a command in another codebase, there are a couple options.",source:"@site/../docs/running_programmatically.md",sourceDirName:".",slug:"/running_programmatically",permalink:"/docs/running_programmatically",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/running_programmatically.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711137687,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Running Commands Programmatically"},sidebar:"docs",previous:{title:"Testing",permalink:"/docs/testing"},next:{title:"Just-in-Time Plugin Installation",permalink:"/docs/jit_plugins"}},c={},l=[{value:"Sharing code with modules",id:"sharing-code-with-modules",level:2},{value:"Calling commands directly",id:"calling-commands-directly",level:2}];function d(n){const e={a:"a",code:"code",em:"em",h2:"h2",p:"p",pre:"pre",strong:"strong",...(0,s.R)(),...n.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(e.p,{children:"If you need to run a command from another, or programmatically run a command in another codebase, there are a couple options."}),"\n",(0,a.jsx)(e.p,{children:"First, it is generally a bad idea to run a command directly as the command exports a user interface, not a code interface. It's a design smell that should rarely (if ever) be used. Generally speaking, it's better to break up the code so that it can be called directly rather than as a command. We'll show this better method first."}),"\n",(0,a.jsx)(e.h2,{id:"sharing-code-with-modules",children:"Sharing code with modules"}),"\n",(0,a.jsxs)(e.p,{children:["For example, if we use ",(0,a.jsx)(e.code,{children:"sf config list"})," as an example, we could have a command that outputs the config vars of an app to the screen like this:"]}),"\n",(0,a.jsx)(e.p,{children:(0,a.jsx)(e.strong,{children:"./src/commands/config/list.ts"})}),"\n",(0,a.jsx)(e.pre,{children:(0,a.jsx)(e.code,{className:"language-typescript",children:"export class ConfigList extends Command {\n static flags = {\n app: Flags.string({required: true})\n }\n\n async run() {\n const {flags} = await this.parse(ConfigList)\n const config = await api.get(`/apps/${flags.app}/config-vars`)\n for (let [key, value] of Object.entries(config)) {\n this.log(`${key}=${value}`)\n }\n }\n}\n"})}),"\n",(0,a.jsxs)(e.p,{children:["If we had another command such as ",(0,a.jsx)(e.code,{children:"sf config update"})," that would do some logic then display the config variables using the same logic, we should create a new module that we could call directly:"]}),"\n",(0,a.jsx)(e.p,{children:(0,a.jsx)(e.strong,{children:"./src/commands/config/update.ts"})}),"\n",(0,a.jsx)(e.pre,{children:(0,a.jsx)(e.code,{className:"language-typescript",children:"import {displayConfigVars} from '../displayConfigVars'\n\nexport class ConfigUpdate extends Command {\n static flags = {\n app: Flags.string({required: true})\n }\n\n async run() {\n const {flags} = await this.parse(ConfigUpdate)\n await this.doUpdate(flags.app)\n await displayConfigVars(flags.app)\n }\n}\n"})}),"\n",(0,a.jsx)(e.p,{children:(0,a.jsx)(e.strong,{children:"./src/displayConfigVars.ts"})}),"\n",(0,a.jsx)(e.pre,{children:(0,a.jsx)(e.code,{className:"language-typescript",children:"export async function displayConfigVars(app: string) {\n const config = await api.get(`/apps/${app}config-vars`)\n for (let [key, value] of Object.entries(config)) {\n this.log(`${key}=${value}`)\n }\n}\n"})}),"\n",(0,a.jsx)(e.p,{children:"This is the recommended way to share code. This can be extended further by putting shared code into its own npm package."}),"\n",(0,a.jsx)(e.h2,{id:"calling-commands-directly",children:"Calling commands directly"}),"\n",(0,a.jsxs)(e.p,{children:["Still, if you ",(0,a.jsx)(e.em,{children:"really"})," want to call a command directly, it's easy to do. You have a couple of options."]}),"\n",(0,a.jsxs)(e.p,{children:["If you know that the command you want to run is installed in the CLI, you can use ",(0,a.jsx)(e.code,{children:"this.config.runCommand"}),". For this, we could write our ",(0,a.jsx)(e.code,{children:"sf config update"})," command like so:"]}),"\n",(0,a.jsx)(e.p,{children:(0,a.jsx)(e.strong,{children:"./src/commands/config/update.ts"})}),"\n",(0,a.jsx)(e.pre,{children:(0,a.jsx)(e.code,{className:"language-typescript",children:"export class ConfigUpdate extends Command {\n static flags = {\n app: Flags.string({required: true})\n }\n\n async run() {\n const {flags} = await this.parse(ConfigUpdate)\n await this.doUpdate(flags.app)\n await this.config.runCommand('config:list', ['--global'])\n }\n}\n"})}),"\n",(0,a.jsx)(e.p,{children:"Or you could import the command directly and execute it directly like so:"}),"\n",(0,a.jsx)(e.p,{children:(0,a.jsx)(e.strong,{children:"./src/commands/config/update.ts"})}),"\n",(0,a.jsx)(e.pre,{children:(0,a.jsx)(e.code,{className:"language-typescript",children:"import {ConfigList} from './config/list'\n\nexport class ConfigUpdate extends Command {\n static flags = {\n app: Flags.string({required: true})\n }\n\n async run() {\n const {flags} = await this.parse(ConfigUpdate)\n await this.doUpdate(flags.app)\n await ConfigList.run(['--global'])\n }\n}\n"})}),"\n",(0,a.jsxs)(e.p,{children:["This works because commands have a static ",(0,a.jsx)(e.code,{children:".run()"})," ",(0,a.jsx)(e.a,{href:"https://github.com/oclif/core/blob/main/src/command.ts",children:"method on them"})," that can be used to instantiate the command and run the instance ",(0,a.jsx)(e.code,{children:".run()"})," method. It takes in the argv as input to the command."]})]})}function p(n={}){const{wrapper:e}={...(0,s.R)(),...n.components};return e?(0,a.jsx)(e,{...n,children:(0,a.jsx)(d,{...n})}):d(n)}},8453:(n,e,t)=>{t.d(e,{R:()=>o,x:()=>r});var a=t(6540);const s={},i=a.createContext(s);function o(n){const e=a.useContext(i);return a.useMemo((function(){return"function"==typeof n?n(e):{...e,...n}}),[e,n])}function r(n){let e;return e=n.disableParentContext?"function"==typeof n.components?n.components(s):n.components||s:o(n.components),a.createElement(i.Provider,{value:e},n.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/935116ff.dc866d9f.js b/assets/js/935116ff.ac0cfaa9.js
similarity index 99%
rename from assets/js/935116ff.dc866d9f.js
rename to assets/js/935116ff.ac0cfaa9.js
index 23b9c762..7a0ff477 100644
--- a/assets/js/935116ff.dc866d9f.js
+++ b/assets/js/935116ff.ac0cfaa9.js
@@ -1 +1 @@
-"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[8212],{1687:(e,t,o)=>{o.r(t),o.d(t,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>s,metadata:()=>a,toc:()=>d});var i=o(4848),n=o(8453);const s={title:"FAQs"},r=void 0,a={id:"faqs",title:"FAQs",description:"Why Node?",source:"@site/../docs/faqs.md",sourceDirName:".",slug:"/faqs",permalink:"/docs/faqs",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/faqs.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711121897,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"FAQs"},sidebar:"docs",previous:{title:"Features",permalink:"/docs/features"},next:{title:"Generator Commands",permalink:"/docs/generator_commands"}},l={},d=[{value:"Why Node?",id:"why-node",level:2},{value:"I want a single binary CLI like with Go",id:"i-want-a-single-binary-cli-like-with-go",level:2},{value:"Should I use TypeScript or JavaScript?",id:"should-i-use-typescript-or-javascript",level:2},{value:"What editor is best for oclif?",id:"what-editor-is-best-for-oclif",level:2},{value:"Should I use npm or yarn?",id:"should-i-use-npm-or-yarn",level:2},{value:"How can I make the oclif generator run faster?",id:"how-can-i-make-the-oclif-generator-run-faster",level:2},{value:"Why isn't Node X supported?",id:"why-isnt-node-x-supported",level:2},{value:"How do I pronounce "oclif"?",id:"how-do-i-pronounce-oclif",level:2}];function c(e){const t={a:"a",code:"code",h2:"h2",p:"p",...(0,n.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(t.h2,{id:"why-node",children:"Why Node?"}),"\n",(0,i.jsxs)(t.p,{children:["There are a number of reasons why Node is the best choice for writing CLI code. At Salesforce, we've released the heroku CLI in Ruby, Go, as well as Node. ",(0,i.jsx)(t.a,{href:"https://blog.heroku.com/evolution-of-heroku-cli-2008-2017",children:"This article gets more into detail on that history"}),", but we've certainly found that Node offers the best of everything."]}),"\n",(0,i.jsx)(t.p,{children:"First, JavaScript is the biggest language in the world. More people are able to write JavaScript than any other language and it by far has the biggest open source community. Everyone can write it and you'll find the most helpful libraries to help build your CLI."}),"\n",(0,i.jsx)(t.p,{children:"We've found that Node has the best cross platform support of any language we've used. In general, if you write code on macOS, you won't find many issues making it also run on Windows."}),"\n",(0,i.jsxs)(t.p,{children:["Node has the best support for our ",(0,i.jsx)(t.a,{href:"/docs/plugins",children:"plugins"})," model. Plugins are a way to share code between CLIs, to modularize a CLIs codebase, or allow users to add functionality to an existing CLI. With Node, we're able to have separate dependency versions sitting alongside one another. This means if you want to release an update to a dependency in one plugin, it won't affect how another plugin works. oclif takes this to an extreme and even flag parsing is done at the individual plugin level. If we ever want to make a breaking change to flag parsing (we certainly don't intend to, but this is just an example), you can update just one plugin and keep the old behavior in other plugins. This is very helpful for large CLI codebases where you want to migrate to new code slowly."]}),"\n",(0,i.jsx)(t.h2,{id:"i-want-a-single-binary-cli-like-with-go",children:"I want a single binary CLI like with Go"}),"\n",(0,i.jsxs)(t.p,{children:["Use ",(0,i.jsx)(t.a,{href:"https://github.com/zeit/pkg",children:"pkg"}),". Just make sure to add the commands and other source files by setting ",(0,i.jsx)(t.code,{children:'pkg.scripts: "./lib/**/*.js"'})," in ",(0,i.jsx)(t.code,{children:"package.json"}),"."]}),"\n",(0,i.jsxs)(t.p,{children:["In the Salesforce CLI, however, we prefer to ship a tarball (and various installers) that has Node baked in. Use ",(0,i.jsx)(t.code,{children:"oclif pack"})," to create a set of tarballs for different platforms with Node built in. You'll likely need to use ",(0,i.jsx)(t.a,{href:"https://github.com/oclif/plugin-update",children:"@oclif/plugin-update"})," with this, otherwise the users won't have a way to update the CLI from the tarball without reinstalling it."]}),"\n",(0,i.jsx)(t.h2,{id:"should-i-use-typescript-or-javascript",children:"Should I use TypeScript or JavaScript?"}),"\n",(0,i.jsx)(t.p,{children:"We suggest TypeScript as we find the typing to really help when refactoring code and updating dependencies. It's nicer to get compilation errors rather than finding errors in production."}),"\n",(0,i.jsxs)(t.p,{children:["We've put a lot of care into making it easy to make a TypeScript CLI even if you've never written TypeScript before. We generate CLIs and plugins that use ",(0,i.jsx)(t.a,{href:"https://github.com/TypeStrong/ts-node",children:"ts-node"})," to make it fast to run the TypeScript code without a compilation step. You won't have to mess around with build configuration using oclif."]}),"\n",(0,i.jsx)(t.p,{children:"Still, the languages today are very similar. The code you write in JavaScript will be nearly identical to what you would have in TypeScript. (Just no type definitions, of course)"}),"\n",(0,i.jsx)(t.h2,{id:"what-editor-is-best-for-oclif",children:"What editor is best for oclif?"}),"\n",(0,i.jsxs)(t.p,{children:["Of course if you already have a go-to editor, you should use that. However, we typically recommend ",(0,i.jsx)(t.a,{href:"https://code.visualstudio.com",children:"vscode"}),"."]}),"\n",(0,i.jsx)(t.p,{children:"Microsoft has done a great job with this editor and it works particularly well in TypeScript projects. You'll get nice type checking, linting, and autocomplete right out of the box."}),"\n",(0,i.jsx)(t.h2,{id:"should-i-use-npm-or-yarn",children:"Should I use npm or yarn?"}),"\n",(0,i.jsx)(t.p,{children:"It really doesn't make that much of a difference. If you're just getting started, keep it simple and use npm which comes with Node. We like to use yarn internally as it's a bit faster and we find the lockfiles friendlier."}),"\n",(0,i.jsx)(t.h2,{id:"how-can-i-make-the-oclif-generator-run-faster",children:"How can I make the oclif generator run faster?"}),"\n",(0,i.jsxs)(t.p,{children:["If you're using npx, install it first with ",(0,i.jsx)(t.code,{children:"npm install -g oclif"}),". This won't stay current with updates though, so you'll need to run ",(0,i.jsx)(t.code,{children:"npm update -g oclif"})," to get new versions of the generator."]}),"\n",(0,i.jsx)(t.h2,{id:"why-isnt-node-x-supported",children:"Why isn't Node X supported?"}),"\n",(0,i.jsxs)(t.p,{children:["The oclif project follows and supports ",(0,i.jsx)(t.a,{href:"https://nodejs.org/en/about/releases/",children:"Node's LTS support schedule"}),". This allows oclif to stay current with Node's development."]}),"\n",(0,i.jsx)(t.h2,{id:"how-do-i-pronounce-oclif",children:'How do I pronounce "oclif"?'}),"\n",(0,i.jsx)(t.p,{children:'We say "oh-cliff".'})]})}function h(e={}){const{wrapper:t}={...(0,n.R)(),...e.components};return t?(0,i.jsx)(t,{...e,children:(0,i.jsx)(c,{...e})}):c(e)}},8453:(e,t,o)=>{o.d(t,{R:()=>r,x:()=>a});var i=o(6540);const n={},s=i.createContext(n);function r(e){const t=i.useContext(s);return i.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function a(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(n):e.components||n:r(e.components),i.createElement(s.Provider,{value:t},e.children)}}}]);
\ No newline at end of file
+"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[8212],{1687:(e,t,o)=>{o.r(t),o.d(t,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>s,metadata:()=>a,toc:()=>d});var i=o(4848),n=o(8453);const s={title:"FAQs"},r=void 0,a={id:"faqs",title:"FAQs",description:"Why Node?",source:"@site/../docs/faqs.md",sourceDirName:".",slug:"/faqs",permalink:"/docs/faqs",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/faqs.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711137687,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"FAQs"},sidebar:"docs",previous:{title:"Features",permalink:"/docs/features"},next:{title:"Generator Commands",permalink:"/docs/generator_commands"}},l={},d=[{value:"Why Node?",id:"why-node",level:2},{value:"I want a single binary CLI like with Go",id:"i-want-a-single-binary-cli-like-with-go",level:2},{value:"Should I use TypeScript or JavaScript?",id:"should-i-use-typescript-or-javascript",level:2},{value:"What editor is best for oclif?",id:"what-editor-is-best-for-oclif",level:2},{value:"Should I use npm or yarn?",id:"should-i-use-npm-or-yarn",level:2},{value:"How can I make the oclif generator run faster?",id:"how-can-i-make-the-oclif-generator-run-faster",level:2},{value:"Why isn't Node X supported?",id:"why-isnt-node-x-supported",level:2},{value:"How do I pronounce "oclif"?",id:"how-do-i-pronounce-oclif",level:2}];function c(e){const t={a:"a",code:"code",h2:"h2",p:"p",...(0,n.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(t.h2,{id:"why-node",children:"Why Node?"}),"\n",(0,i.jsxs)(t.p,{children:["There are a number of reasons why Node is the best choice for writing CLI code. At Salesforce, we've released the heroku CLI in Ruby, Go, as well as Node. ",(0,i.jsx)(t.a,{href:"https://blog.heroku.com/evolution-of-heroku-cli-2008-2017",children:"This article gets more into detail on that history"}),", but we've certainly found that Node offers the best of everything."]}),"\n",(0,i.jsx)(t.p,{children:"First, JavaScript is the biggest language in the world. More people are able to write JavaScript than any other language and it by far has the biggest open source community. Everyone can write it and you'll find the most helpful libraries to help build your CLI."}),"\n",(0,i.jsx)(t.p,{children:"We've found that Node has the best cross platform support of any language we've used. In general, if you write code on macOS, you won't find many issues making it also run on Windows."}),"\n",(0,i.jsxs)(t.p,{children:["Node has the best support for our ",(0,i.jsx)(t.a,{href:"/docs/plugins",children:"plugins"})," model. Plugins are a way to share code between CLIs, to modularize a CLIs codebase, or allow users to add functionality to an existing CLI. With Node, we're able to have separate dependency versions sitting alongside one another. This means if you want to release an update to a dependency in one plugin, it won't affect how another plugin works. oclif takes this to an extreme and even flag parsing is done at the individual plugin level. If we ever want to make a breaking change to flag parsing (we certainly don't intend to, but this is just an example), you can update just one plugin and keep the old behavior in other plugins. This is very helpful for large CLI codebases where you want to migrate to new code slowly."]}),"\n",(0,i.jsx)(t.h2,{id:"i-want-a-single-binary-cli-like-with-go",children:"I want a single binary CLI like with Go"}),"\n",(0,i.jsxs)(t.p,{children:["Use ",(0,i.jsx)(t.a,{href:"https://github.com/zeit/pkg",children:"pkg"}),". Just make sure to add the commands and other source files by setting ",(0,i.jsx)(t.code,{children:'pkg.scripts: "./lib/**/*.js"'})," in ",(0,i.jsx)(t.code,{children:"package.json"}),"."]}),"\n",(0,i.jsxs)(t.p,{children:["In the Salesforce CLI, however, we prefer to ship a tarball (and various installers) that has Node baked in. Use ",(0,i.jsx)(t.code,{children:"oclif pack"})," to create a set of tarballs for different platforms with Node built in. You'll likely need to use ",(0,i.jsx)(t.a,{href:"https://github.com/oclif/plugin-update",children:"@oclif/plugin-update"})," with this, otherwise the users won't have a way to update the CLI from the tarball without reinstalling it."]}),"\n",(0,i.jsx)(t.h2,{id:"should-i-use-typescript-or-javascript",children:"Should I use TypeScript or JavaScript?"}),"\n",(0,i.jsx)(t.p,{children:"We suggest TypeScript as we find the typing to really help when refactoring code and updating dependencies. It's nicer to get compilation errors rather than finding errors in production."}),"\n",(0,i.jsxs)(t.p,{children:["We've put a lot of care into making it easy to make a TypeScript CLI even if you've never written TypeScript before. We generate CLIs and plugins that use ",(0,i.jsx)(t.a,{href:"https://github.com/TypeStrong/ts-node",children:"ts-node"})," to make it fast to run the TypeScript code without a compilation step. You won't have to mess around with build configuration using oclif."]}),"\n",(0,i.jsx)(t.p,{children:"Still, the languages today are very similar. The code you write in JavaScript will be nearly identical to what you would have in TypeScript. (Just no type definitions, of course)"}),"\n",(0,i.jsx)(t.h2,{id:"what-editor-is-best-for-oclif",children:"What editor is best for oclif?"}),"\n",(0,i.jsxs)(t.p,{children:["Of course if you already have a go-to editor, you should use that. However, we typically recommend ",(0,i.jsx)(t.a,{href:"https://code.visualstudio.com",children:"vscode"}),"."]}),"\n",(0,i.jsx)(t.p,{children:"Microsoft has done a great job with this editor and it works particularly well in TypeScript projects. You'll get nice type checking, linting, and autocomplete right out of the box."}),"\n",(0,i.jsx)(t.h2,{id:"should-i-use-npm-or-yarn",children:"Should I use npm or yarn?"}),"\n",(0,i.jsx)(t.p,{children:"It really doesn't make that much of a difference. If you're just getting started, keep it simple and use npm which comes with Node. We like to use yarn internally as it's a bit faster and we find the lockfiles friendlier."}),"\n",(0,i.jsx)(t.h2,{id:"how-can-i-make-the-oclif-generator-run-faster",children:"How can I make the oclif generator run faster?"}),"\n",(0,i.jsxs)(t.p,{children:["If you're using npx, install it first with ",(0,i.jsx)(t.code,{children:"npm install -g oclif"}),". This won't stay current with updates though, so you'll need to run ",(0,i.jsx)(t.code,{children:"npm update -g oclif"})," to get new versions of the generator."]}),"\n",(0,i.jsx)(t.h2,{id:"why-isnt-node-x-supported",children:"Why isn't Node X supported?"}),"\n",(0,i.jsxs)(t.p,{children:["The oclif project follows and supports ",(0,i.jsx)(t.a,{href:"https://nodejs.org/en/about/releases/",children:"Node's LTS support schedule"}),". This allows oclif to stay current with Node's development."]}),"\n",(0,i.jsx)(t.h2,{id:"how-do-i-pronounce-oclif",children:'How do I pronounce "oclif"?'}),"\n",(0,i.jsx)(t.p,{children:'We say "oh-cliff".'})]})}function h(e={}){const{wrapper:t}={...(0,n.R)(),...e.components};return t?(0,i.jsx)(t,{...e,children:(0,i.jsx)(c,{...e})}):c(e)}},8453:(e,t,o)=>{o.d(t,{R:()=>r,x:()=>a});var i=o(6540);const n={},s=i.createContext(n);function r(e){const t=i.useContext(s);return i.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function a(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(n):e.components||n:r(e.components),i.createElement(s.Provider,{value:t},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/9b8720eb.9058c84e.js b/assets/js/9b8720eb.9058c84e.js
new file mode 100644
index 00000000..8f192cc6
--- /dev/null
+++ b/assets/js/9b8720eb.9058c84e.js
@@ -0,0 +1 @@
+"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[1406],{7908:(e,t,o)=>{o.r(t),o.d(t,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>a,metadata:()=>s,toc:()=>c});var i=o(4848),n=o(8453);const a={title:"oclifconf 2019: A Recap"},r=void 0,s={permalink:"/blog/2019/09/16/oclifconf-recap",source:"@site/blog/2019-09-16-oclifconf-recap.md",title:"oclifconf 2019: A Recap",description:"In May, Heroku and Salesforce Open Source organized oclifconf, a conference for developers & product managers building CLI tools on top of the open source oclif framework. The speakers came from various tech companies, such as Adobe, Netlify, and Apollo, who have already built amazing CLI experiences. The topics covered everything from the incredible capabilities oclif has unlocked, to the community-built plugins extending its functionality, and even what the behavior of an adaptive CLI tool might look like.",date:"2019-09-16T00:00:00.000Z",formattedDate:"September 16, 2019",tags:[],readingTime:3.56,hasTruncateMarker:!1,authors:[],frontMatter:{title:"oclifconf 2019: A Recap"},unlisted:!1,prevItem:{title:"oclif's Current Node Support",permalink:"/blog/2019/10/31/oclif-node-updates"},nextItem:{title:"CLI Flags Explained",permalink:"/blog/2019/02/20/cli-flags-explained"}},l={authorsImageUrls:[]},c=[{value:"The future of oclif by Jeff Dickey",id:"the-future-of-oclif-by-jeff-dickey",level:2},{value:"Open Source Citizenship by Josh Simmons",id:"open-source-citizenship-by-josh-simmons",level:2},{value:"Building an enterprise-grade CLI with oclif by Thomas Dvornik",id:"building-an-enterprise-grade-cli-with-oclif-by-thomas-dvornik",level:2},{value:"How Adobe I/O built an extensible CLI with oclif by Jesse MacFadyen",id:"how-adobe-io-built-an-extensible-cli-with-oclif-by-jesse-macfadyen",level:2},{value:"Integrating oclif with GraphQL and Apollo by Evans Hauser",id:"integrating-oclif-with-graphql-and-apollo-by-evans-hauser",level:2},{value:"Adaptive Intent-based CLI State Machines by Shawn Wang",id:"adaptive-intent-based-cli-state-machines-by-shawn-wang",level:2}];function d(e){const t={a:"a",h2:"h2",p:"p",...(0,n.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsxs)(t.p,{children:["In May, Heroku and Salesforce Open Source organized ",(0,i.jsx)(t.a,{href:"https://oclif.io/conf",children:"oclifconf"}),", a conference for developers & product managers building CLI tools on top of ",(0,i.jsx)(t.a,{href:"https://github.com/oclif/oclif",children:"the open source oclif framework"}),". The speakers came from various tech companies, such as Adobe, Netlify, and Apollo, who have already built amazing CLI experiences. The topics covered everything from the incredible capabilities oclif has unlocked, to the community-built plugins extending its functionality, and even what the behavior of an adaptive CLI tool might look like."]}),"\n",(0,i.jsx)(t.p,{children:"Below is a listing of all of the talks from the event, along with a short summary. Enjoy!"}),"\n",(0,i.jsx)(t.h2,{id:"the-future-of-oclif-by-jeff-dickey",children:"The future of oclif by Jeff Dickey"}),"\n",(0,i.jsx)("iframe",{width:"560",height:"315",src:"https://www.youtube-nocookie.com/embed/1TKh2YBxRMY",frameborder:"0",allow:"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture",allowFullScreen:!0}),"\n",(0,i.jsxs)(t.p,{children:["In its relatively short lifetime, oclif has already inspired many developers and companies to adopt its framework as a means for implementing their own command-line tooling. In this talk, Jeff Dickey, an oclif founding team member, recaps the project's history and inspiration. He also looks towards the future and outlines some features and improvements that the tool could adapt. This isn't so much a definitive roadmap of where oclif is headed, but rather, a call to inspiration for developers eager to contribute! And if you are interested in contributing, check out the ",(0,i.jsx)(t.a,{href:"https://github.com/oclif/oclif/issues",children:"open issues"}),' in the oclif GitHub repo and come say "Hello!" on ',(0,i.jsx)(t.a,{href:"https://spectrum.chat/oclif",children:"Spectrum Chat"}),"."]}),"\n",(0,i.jsx)(t.h2,{id:"open-source-citizenship-by-josh-simmons",children:"Open Source Citizenship by Josh Simmons"}),"\n",(0,i.jsx)("iframe",{width:"560",height:"315",src:"https://www.youtube-nocookie.com/embed/54hhR5DoV6g",frameborder:"0",allow:"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture",allowFullScreen:!0}),"\n",(0,i.jsx)(t.p,{children:"When it comes to open source, it's more than just individuals now. More and more frequently, large corporations are contributing to projects by donating to contributors, sponsoring events, or upstreaming contributions. But keeping open source projects and communities healthy requires more than just money and brainpower. Josh Simmons surveyed multiple open source communities and relays his findings as to what help maintainers and contributors actually need in this talk."}),"\n",(0,i.jsx)(t.h2,{id:"building-an-enterprise-grade-cli-with-oclif-by-thomas-dvornik",children:"Building an enterprise-grade CLI with oclif by Thomas Dvornik"}),"\n",(0,i.jsx)("iframe",{width:"560",height:"315",src:"https://www.youtube-nocookie.com/embed/v4saIi5zoy8",frameborder:"0",allow:"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture",allowFullScreen:!0}),"\n",(0,i.jsx)(t.p,{children:"Security and performance are all about trust. While oclif is an extremely extensible framework for building CLI tooling, there are additional requirements to fulfill for enterprise businesses to adopt it that might not be necessary for individual developers. Thomas Dvornik outlines what he and his colleagues at Salesforce have implemented as plugins to oclif to satisfy these needs, including encrypted OAuth, plugin signing, lazy loading dependencies, synchronizing weekly releases and deprecations across dozens of repositories, and establishing cross-team coding and documentation standards."}),"\n",(0,i.jsx)(t.h2,{id:"how-adobe-io-built-an-extensible-cli-with-oclif-by-jesse-macfadyen",children:"How Adobe I/O built an extensible CLI with oclif by Jesse MacFadyen"}),"\n",(0,i.jsx)("iframe",{width:"560",height:"315",src:"https://www.youtube-nocookie.com/embed/Mxhx1wmoHlA",frameborder:"0",allow:"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture",allowFullScreen:!0}),"\n",(0,i.jsx)(t.p,{children:"Perhaps oclif's most appealing feature is its support for plugins. In Cordova's case, they've created a sophisticated telemetry system that helps Adobe developers see which commands users are using--and reports on which ones are erroring out. By embedding a feedback system into the tool, users are even able to quickly send their suggestions to a form, without ever leaving the terminal. Jesse MacFadyen demonstrates how oclif's plugin system can work beyond simply executing commands."}),"\n",(0,i.jsx)(t.h2,{id:"integrating-oclif-with-graphql-and-apollo-by-evans-hauser",children:"Integrating oclif with GraphQL and Apollo by Evans Hauser"}),"\n",(0,i.jsx)("iframe",{width:"560",height:"315",src:"https://www.youtube-nocookie.com/embed/Zh78npkypas",frameborder:"0",allow:"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture",allowFullScreen:!0}),"\n",(0,i.jsx)(t.p,{children:'For Evans Hauser and the team at Apollo, oclif is best thought of as "React for the CLI." As a client paired with a strongly-typed API contract to a server, it can deliver structured and consistent commands to retrieve external data. What better mechanism to use for this transfer than GraphQL, a framework which empowers the client to ask precisely for the data it needs, and nothing more?'}),"\n",(0,i.jsx)(t.h2,{id:"adaptive-intent-based-cli-state-machines-by-shawn-wang",children:"Adaptive Intent-based CLI State Machines by Shawn Wang"}),"\n",(0,i.jsx)("iframe",{width:"560",height:"315",src:"https://www.youtube-nocookie.com/embed/ZueoIYnHiaI",frameborder:"0",allow:"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture",allowFullScreen:!0}),"\n",(0,i.jsxs)(t.p,{children:["In designing oclif, ",(0,i.jsx)(t.a,{href:"https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46",children:"Jeff Dickey wrote out 12 CLI factors to keep in mind"}),". In this talk, Shawn Wang outlines a 13th: state. State is hard, because it depends on context, and context depends on understanding what a user intends to do, not what they are asking. Shawn is working towards enabling oclif to better understand the commands a user has entered, so that it can predict and interpret future commands that might be entered next. This would enable CLI tools to not just interpret a users' commands, but to also interpret their intent."]})]})}function h(e={}){const{wrapper:t}={...(0,n.R)(),...e.components};return t?(0,i.jsx)(t,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},8453:(e,t,o)=>{o.d(t,{R:()=>r,x:()=>s});var i=o(6540);const n={},a=i.createContext(n);function r(e){const t=i.useContext(a);return i.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function s(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(n):e.components||n:r(e.components),i.createElement(a.Provider,{value:t},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/9eaa546a.45d375f7.js b/assets/js/9eaa546a.c0f4d728.js
similarity index 99%
rename from assets/js/9eaa546a.45d375f7.js
rename to assets/js/9eaa546a.c0f4d728.js
index a6fe5526..618cf69d 100644
--- a/assets/js/9eaa546a.45d375f7.js
+++ b/assets/js/9eaa546a.c0f4d728.js
@@ -1 +1 @@
-"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[4711],{2449:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>r,contentTitle:()=>a,default:()=>u,frontMatter:()=>s,metadata:()=>l,toc:()=>c});var o=n(4848),i=n(8453);const s={title:"Features"},a=void 0,l={id:"features",title:"Features",description:"Flag/Argument parsing",source:"@site/../docs/features.md",sourceDirName:".",slug:"/features",permalink:"/docs/features",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/features.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711121897,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Features"},sidebar:"docs",previous:{title:"Introduction",permalink:"/docs/introduction"},next:{title:"FAQs",permalink:"/docs/faqs"}},r={},c=[{value:"Flag/Argument parsing",id:"flagargument-parsing",level:3},{value:"Configurable Topic Separators",id:"configurable-topic-separators",level:3},{value:"Super Speed",id:"super-speed",level:3},{value:"CLI Generator",id:"cli-generator",level:3},{value:"Testing Helpers",id:"testing-helpers",level:3},{value:"Auto-documentation",id:"auto-documentation",level:3},{value:"Plugins",id:"plugins",level:3},{value:"Hooks",id:"hooks",level:3},{value:"JSON Output",id:"json-output",level:3},{value:"TypeScript (or not)",id:"typescript-or-not",level:3},{value:"Auto-updating Installers",id:"auto-updating-installers",level:3},{value:"Autocomplete",id:"autocomplete",level:3}];function d(e){const t={a:"a",code:"code",h3:"h3",p:"p",pre:"pre",...(0,i.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(t.h3,{id:"flagargument-parsing",children:"Flag/Argument parsing"}),"\n",(0,o.jsx)(t.p,{children:"No CLI framework would be complete without a flag parser. We've built a custom one from years of experimentation that we feel consistently handles user input flexible enough for the user to be able to easily use the CLI in ways they expect, but without compromising strictness guarantees to the developer."}),"\n",(0,o.jsx)(t.h3,{id:"configurable-topic-separators",children:"Configurable Topic Separators"}),"\n",(0,o.jsxs)(t.p,{children:["By default topics will be separated with colons, e.g. ",(0,o.jsx)(t.code,{children:"my:awesome:command"}),". However, you have the option to use spaces if you prefer, e.g. ",(0,o.jsx)(t.code,{children:"my awesome command"}),"."]}),"\n",(0,o.jsx)(t.h3,{id:"super-speed",children:"Super Speed"}),"\n",(0,o.jsxs)(t.p,{children:["The overhead for running an oclif CLI command is almost nothing. ",(0,o.jsx)(t.a,{href:"https://www.npmjs.com/package/@oclif/core?activeTab=dependencies",children:"It requires very few dependencies"})," (only 28 dependencies in a minimal setup\u2014including all transitive dependencies). Also, only the command to be executed will be required with node. So large CLIs with many commands will load just as fast as a small one with a single command."]}),"\n",(0,o.jsx)(t.h3,{id:"cli-generator",children:"CLI Generator"}),"\n",(0,o.jsxs)(t.p,{children:["Run a single command to scaffold out a fully functional CLI and get started quickly. See ",(0,o.jsx)(t.a,{href:"https://oclif.io/docs/generator_commands",children:"Generator Commands"}),"."]}),"\n",(0,o.jsx)(t.h3,{id:"testing-helpers",children:"Testing Helpers"}),"\n",(0,o.jsxs)(t.p,{children:["We've put a lot of work into making commands easily testable and easy to mock out stdout/stderr. The generator will automatically create ",(0,o.jsx)(t.a,{href:"https://github.com/oclif/hello-world/blob/main/test/commands/hello/world.test.ts",children:"scaffolded tests"}),"."]}),"\n",(0,o.jsx)(t.h3,{id:"auto-documentation",children:"Auto-documentation"}),"\n",(0,o.jsxs)(t.p,{children:["By default you can pass ",(0,o.jsx)(t.code,{children:"--help"})," to the CLI to get help such as flag options and argument information. This information is also automatically placed in the README whenever the npm package of the CLI is published. See the ",(0,o.jsx)(t.a,{href:"https://github.com/oclif/hello-world",children:"hello-world CLI example"})]}),"\n",(0,o.jsx)(t.h3,{id:"plugins",children:"Plugins"}),"\n",(0,o.jsxs)(t.p,{children:["Using plugins, users of the CLI can extend it with new functionality, a CLI can be split into modular components, and functionality can be shared amongst multiple CLIs. See ",(0,o.jsx)(t.a,{href:"https://oclif.io/docs/plugins#building-your-own-plugin",children:"Building your own plugin"}),"."]}),"\n",(0,o.jsx)(t.h3,{id:"hooks",children:"Hooks"}),"\n",(0,o.jsxs)(t.p,{children:["Use lifecycle hooks to run functionality any time a CLI starts, or on custom triggers. Use this whenever custom functionality needs to be shared between various components of the CLI. See ",(0,o.jsx)(t.a,{href:"https://oclif.io/docs/hooks",children:"Hooks"}),"."]}),"\n",(0,o.jsx)(t.h3,{id:"json-output",children:"JSON Output"}),"\n",(0,o.jsxs)(t.p,{children:["You can opt-in to using the ",(0,o.jsx)(t.code,{children:"--json"})," flag which will automatically suppress console logs and display the final result of the command as valid JSON output. This is very useful if you want your CLI to be used for scripting in CI/CD environments. See ",(0,o.jsx)(t.a,{href:"https://oclif.io/docs/json",children:"JSON"}),"."]}),"\n",(0,o.jsx)(t.h3,{id:"typescript-or-not",children:"TypeScript (or not)"}),"\n",(0,o.jsxs)(t.p,{children:["Everything in the core of oclif is written in TypeScript and the generator can build fully configured TypeScript CLIs or just plain JavaScript CLIs. By virtue of static properties in TypeScript the syntax is a bit cleaner in TypeScript \u2014 but everything will work no matter which language you choose. If you use plugins support, the CLI will automatically use ",(0,o.jsx)(t.code,{children:"ts-node"})," to run the plugins making it easy and fast to use TypeScript with minimal-to-no boilerplate needed for any oclif CLI."]}),"\n",(0,o.jsx)(t.h3,{id:"auto-updating-installers",children:"Auto-updating Installers"}),"\n",(0,o.jsxs)(t.p,{children:["oclif can package your CLI into ",(0,o.jsx)(t.a,{href:"/docs/releasing",children:"different installers"})," that will not require the user to already have node installed on the machine. These can be made auto-updatable by using ",(0,o.jsx)(t.a,{href:"https://github.com/oclif/plugin-update",children:"plugin-update"}),"."]}),"\n",(0,o.jsx)(t.h3,{id:"autocomplete",children:"Autocomplete"}),"\n",(0,o.jsxs)(t.p,{children:["Include terminal autocompletion for your CLI via ",(0,o.jsx)(t.a,{href:"https://github.com/oclif/plugin-autocomplete",children:"plugin-autocomplete"}),". Once installed, users can complete command names and flag names."]}),"\n",(0,o.jsx)(t.pre,{children:(0,o.jsx)(t.code,{className:"language-bash",children:"$ my-cli p| oclif v1 | \\noclif v2 | \\n
![](\\"/img/2022-01-12-announcing-oclif-v2/sfdx-help.png\\"/) | \\n ![](\\"/img/2022-01-12-announcing-oclif-v2/sf-help.png\\"/) | \\n
\\n\\n### Reference material\\n\\n#### Migration Guide\\n\\nThis guide explains how to upgrade a CLI or plugin from the old oclif v1 libraries to the new `@oclif/core` library that oclif v2 uses.\\n\\nhttps://github.com/oclif/core/blob/main/MIGRATION.md\\n\\n#### Compatibility Matrix\\n\\nThe following matrix shows how the v1 libraries and plugins relate to the new v2 ones. Use this matrix as a guide to know what to drop and which versions to switch when upgrading your plugins and CLIs to v2.\\n\\n| | oclif \\"v1\\" | oclif \\"v2\\" |\\n| - | - | -|\\n| Utility CLIs | oclif@\\\\<2
@oclif/dev-cli@\\\\<2 | oclif@>=2\\n| Main packages | @oclif/command
@oclif/config
@oclif/errors
@oclif/parser
@oclif/plugin-help
| @oclif/core@>=1\\n| Node LTS | Node v8-14 | Node v12+ (at time of writing) |\\n| TypeScript | typescript@\\\\<4 | typescript@>=4 |\\n| Main plugins | @oclif/plugin-autocomplete@\\\\<1
@oclif/plugin-commands@\\\\<2
@oclif/plugin-help@\\\\<4
@oclif/plugin-not-found@\\\\<2
@oclif/plugin-plugins@\\\\<2
@oclif/plugin-update@\\\\<2
plugin-warn-if-update-available@\\\\<2
plugin-which@\\\\<2
| @oclif/plugin-autocomplete@>=1
@oclif/plugin-commands@>=2
@oclif/plugin-help@>=4
@oclif/plugin-not-found@>=2
@oclif/plugin-plugins@>=2
@oclif/plugin-update@>=2
@oclif/plugin-warn-if-update-available@>=2
@oclif/plugin-which@>=2
|"},{"id":"/2021/03/01/introducing-oclif-core","metadata":{"permalink":"/blog/2021/03/01/introducing-oclif-core","source":"@site/blog/2021-03-01-introducing-oclif-core.md","title":"Introducing @oclif/core","description":"Greetings!","date":"2021-03-01T00:00:00.000Z","formattedDate":"March 1, 2021","tags":[],"readingTime":2.18,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"Introducing @oclif/core"},"unlisted":false,"prevItem":{"title":"Announcing oclif v2!","permalink":"/blog/2022/01/12/announcing-oclif-v2"},"nextItem":{"title":"oclif Summer Update","permalink":"/blog/2020/08/26/summer-update"}},"content":"Greetings!\\n\\nWe hope this blog post finds you well.\\n\\n### Introducing...\\n\\nWe are excited to announce the next iteration of the oclif project today: `@oclif/core`.\\n\\nWe have learned a lot in the last three years of developing oclif, developing on oclif and supporting millions of command runs a day via Heroku and Salesforce CLIs.\\n`@oclif/core` (\\"Core\\") simplifies the oclif development experience and introduces highly requested new features.\\n\\nCore combines the essential oclif packages into one \\"core\\" package, aptly named `@oclif/core`.\\n\\nCore also introduces:\\n- A default command option\\n- Colon or space command syntax\\n- Async command parsing\\n- Command piping to arguments\\n\\nWith the introduction of default command functionality, Core simplifies the oclif project and removes the notion of single or multi command CLIs. Core CLIs can have 1 or many commands.\\n\\nAlong with Core, we moved the oclif-dev CLI into the oclif CLI creating a single \\"utility\\" CLI. This CLI also introduces a new AWS S3 compatible publishing scheme.\\n\\n### What to expect in the near future\\n\\nCore is in pre-release beta and being actively developed for new internal Salesforce CLIs.\\n\\nMuch documentation needs to be written in the coming months including migration paths. Migration onto Core should be as painless as possible with many exports remaining entirely unchanged. Look for forthcoming blog posts and documentation on [oclif.io](https://oclif.io).\\n\\nEarly this summer, tentively June 1, we will release Core v1. Core\'s release will coincide with major bumps to many other oclif plugin packages. See the compatibility matrix below.\\n\\nAt Core\'s v1 release, the current \\"main\\" oclif packages (namely: command, config, errors & parser) will go into maintenance mode until Jan 2022. They will receive _only_ bug and security fixes and they remain compatible with current versions of the oclif and oclif-dev CLIs. Afterwhich, they will be archived.\\n\\nCompanioning Core, the next major release of the oclif CLI (literally `oclif@2`) will generate Core CLIs.\\n\\n### Going forward\\n\\nWe are excited to release Core! We invite you to poke around the [Core repo](https://github.com/oclif/core). It may appear to be a big change but Core keeps what you already enjoy about oclif while reducing development complexity, project dependencies, package coupling and bundle size and introduces many requested features previously too prickly to weave into the current oclif architecture.\\n\\nBest,\\n\\nThe oclif team\\n\\n#### Reference: Compatibility matrix\\n\\n| | oclif \\"v1\\" | oclif \\"Core\\" |\\n| - | - | -|\\n| Utility CLIs | oclif@\\\\<2
@oclif/dev-cli@\\\\<2 | oclif@>=2\\n| Main packages | @oclif/core@\\\\<2
@oclif/config@\\\\<2
@oclif/errors@\\\\<2
@oclif/parser@\\\\<4
@oclif/plugin-help@\\\\<4
| @oclif/core@>=1\\n| Node LTS | Node v8-14 | Node v12+ |\\n| TypeScript | typescript@\\\\<4 | typescript@>=4 |\\n| Main plugins | @oclif/plugin-autocomplete@\\\\<1
@oclif/plugin-commands@\\\\<2
@oclif/plugin-help@\\\\<4
@oclif/plugin-not-found@\\\\<2
@oclif/plugin-plugins@\\\\<2
@oclif/plugin-update@\\\\<2
plugin-warn-if-update-available@\\\\<2
plugin-which@\\\\<2
| @oclif/plugin-autocomplete@>=2
@oclif/plugin-commands@>=2
@oclif/plugin-help@>=4
@oclif/plugin-not-found@>=2
@oclif/plugin-plugins@>=2
@oclif/plugin-update@>=2
@oclif/plugin-warn-if-update-available@>=2
@oclif/plugin-which@>=2
|"},{"id":"/2020/08/26/summer-update","metadata":{"permalink":"/blog/2020/08/26/summer-update","source":"@site/blog/2020-08-26-summer-update.md","title":"oclif Summer Update","description":"Hello oclif developers! We hope you are all doing well.","date":"2020-08-26T00:00:00.000Z","formattedDate":"August 26, 2020","tags":[],"readingTime":1.355,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"oclif Summer Update"},"unlisted":false,"prevItem":{"title":"Introducing @oclif/core","permalink":"/blog/2021/03/01/introducing-oclif-core"},"nextItem":{"title":"Pretty Printable Errors","permalink":"/blog/2020/07/01/pretty-printable-errors"}},"content":"Hello oclif developers! We hope you are all doing well.\\n\\nEarlier this year, we started our planning for oclifconf v2 and, like all conference, had to change course. We opted not to hold a virtual conference, however, we wanted to take some time to highlight a few oclif features shipped this year.\\n\\n## Feature: Help templating\\n\\nOne of the most requested features, help templating enables oclif developers to customize the help output for their CLI.\\n\\nRead [the announcement](/blog/introducing-custom-help-classes).\\n\\n## Feature: Custom error delegation\\n\\nThis feature both improved how oclif throws and handles errors and allows oclif developers to overwrite or interject in oclif\u2019s error handling.\\n\\nRead [the announcement](/blog/2020/07/01/pretty-printable-errors).\\n\\n## Feature: postrun hooks\\n\\nWe have added a new lifecycle event `postrun`. Your CLI can now run a hook after a command has ran.\\n\\nSee our [hook documentation](/docs/hooks).\\n\\n## Feature: Root index command\\n\\nPreviously, oclif would display CLI help if only the binary name with no command ID was invoked, oclif now supports a \\"root index\\" command. If present, a command defined at `src/commands/index.ts` will be run if no command ID is found.\\n\\n## 1 million weekly downloads\\n\\nWhile exact oclif usage metrics are hard to pin down, we use npm download statistics of oclif packages as a rough approximation. Earlier this year, oclif\'s command package hit 1 million weekly downloads for the first time!\\n\\n\\nThis year has been presented its challenges on everyone. We want to thank you, oclif developers, whom have taken the time to use and improve the oclif project. We look forward to seeing you all - in person - in the future!\\n\\nAll our best,\\n\\nThe oclif team"},{"id":"/2020/07/01/pretty-printable-errors","metadata":{"permalink":"/blog/2020/07/01/pretty-printable-errors","source":"@site/blog/2020-07-01-pretty-printable-errors.md","title":"Pretty Printable Errors","description":"Often CLIs are used as handy tools and when things go wrong it\u2019s useful to have additional context. In oclif we have added a couple of additional properties that can show extra context to the users when an error is displayed. The code, ref and suggestions will now be displayed if they are included. This will work with an existing oclif CLI by adding the latest @oclif/errors and @oclif/core to the CLI\'s package.json dependencies.","date":"2020-07-01T00:00:00.000Z","formattedDate":"July 1, 2020","tags":[],"readingTime":0.995,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"Pretty Printable Errors"},"unlisted":false,"prevItem":{"title":"oclif Summer Update","permalink":"/blog/2020/08/26/summer-update"},"nextItem":{"title":"Customizing Help in oclif","permalink":"/blog/2020/05/05/introducing-custom-help-classes"}},"content":"Often CLIs are used as handy tools and when things go wrong it\u2019s useful to have additional context. In oclif we have added a couple of additional properties that can show extra context to the users when an error is displayed. The `code`, `ref` and `suggestions` will now be displayed if they are included. This will work with an existing oclif CLI by adding the latest @oclif/errors and @oclif/core to the CLI\'s package.json dependencies.\\n\\nFor example, using `this.error` with the additional properties:\\n```js\\nclass TestError extends Command {\\n async run() {\\n this.error(\\"An error has occurred!\\", {\\n code: \\"OCLIF_ERR\\",\\n ref: \\"https://oclif.io/docs/commands#thiserrormessage-string--error-options-code-string-exit-number\\",\\n suggestions: [\\"Use these extra properties to provide additional context\\"],\\n })\\n }\\n}\\n```\\n\\nwould result with the following output:\\n```text\\n\u203a Error: An error has occurred!\\n\u203a Code: OCLIF_ERR\\n\u203a Try this: Use these extra properties to provide additional context\\n\u203a Reference: https://oclif.io/docs/commands#thiserrormessage-string--error-options-code-string-exit-number\\n```\\n\\nIf these properties are not provided then nothing changes and the CLI will continue to display the single error message output as it did before. Additionally, as part of this exercise we\u2019ve added documentation around [Error Handling in oclif](/docs/error_handling) which should come in handy if the need arises to extend oclif\u2019s default handling of errors."},{"id":"/2020/05/05/introducing-custom-help-classes","metadata":{"permalink":"/blog/2020/05/05/introducing-custom-help-classes","source":"@site/blog/2020-05-05-introducing-custom-help-classes.md","title":"Customizing Help in oclif","description":"Out of the box oclif provides a great help experience for CLIs.","date":"2020-05-05T00:00:00.000Z","formattedDate":"May 5, 2020","tags":[],"readingTime":1.67,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"Customizing Help in oclif"},"unlisted":false,"prevItem":{"title":"Pretty Printable Errors","permalink":"/blog/2020/07/01/pretty-printable-errors"},"nextItem":{"title":"oclif TSLint to ESLint Migration","permalink":"/blog/2019/12/05/oclif-eslint-migration"}},"content":"Out of the box oclif provides a great help experience for CLIs.\\n\\nBut what if, as an oclif developer, you want to customize some or all of the output?\\n\\nYou can now customize your CLI\'s help output by implementing the `HelpBase` abstract class.\\n\\n## Getting started with custom help\\n\\nIf you have not done so yet, update `@oclif/core`.\\n\\n\\n```\\n$ yarn add --latest @oclif/core\\n```\\n\\nTo get started, first define the filepath to your help class in oclif\'s config in package.json. This is a relative path to the help class, without a file extension.\\n\\nFor this example, the help class will be created in a file at \\"[project root]/src/help.ts\\".\\n\\n```\\n{\\n // ...\\n \\"oclif\\": {\\n \\"helpClass\\": \\"./lib/help\\"\\n // ...\\n }\\n // ...\\n}\\n```\\n\\nFrom here there are two paths, implement the `HelpBase` abstract class yourself or overwrite the parts of the default `Help` class you want to customize (ex: how command usage is displayed). We recommend the latter approach but cover both in the new [Help Classes docs](../../../../docs/help_classes).\\n\\n\\n## Separating TOPICS & COMMANDS in the new default `Help` class\\n\\nPreviously, topics and child commands were listed in help output under a single list heading called \\"COMMANDS\\". But we found this can be slightly confusing. Some topics are commands also (a.k.a. topic-commands) while others are simply organizational namespacing (and when ran just show their help).\\n\\nThe new default `Help` class splits the list of children into distinct lists of \\"TOPICS\\" and \\"COMMANDS\\", with the possibility of an item appearing in both if it a topic-command. This makes it clearer what is expected to be ran - \\"COMMANDS\\" - and what is providing structure - \\"TOPICS\\" - when looking at the help output.\\n\\n```\\nVERSION\\n plugin-help-example/0.0.0 darwin-x64 node-v12.12.0\\n\\nUSAGE\\n $ plugin-help-example [COMMAND]\\n\\nTOPICS\\n topic this is a topic and has child topics or commands\\n\\nCOMMANDS\\n hello describe the command here\\n help display help for plugin-help-example\\n```\\n\\nWe look forward to seeing what custom help features you implement in your oclif CLIs with this new feature!"},{"id":"/2019/12/05/oclif-eslint-migration","metadata":{"permalink":"/blog/2019/12/05/oclif-eslint-migration","source":"@site/blog/2019-12-05-oclif-eslint-migration.md","title":"oclif TSLint to ESLint Migration","description":"Back in February of this year, plans were announced to deprecate TSLint in favor of ESLint. TSLint\'s goal has become to work toward a \u201cunified developer experience\u201d by supporting ESLint development going forward.","date":"2019-12-05T00:00:00.000Z","formattedDate":"December 5, 2019","tags":[],"readingTime":2.18,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"oclif TSLint to ESLint Migration"},"unlisted":false,"prevItem":{"title":"Customizing Help in oclif","permalink":"/blog/2020/05/05/introducing-custom-help-classes"},"nextItem":{"title":"oclif\'s Current Node Support","permalink":"/blog/2019/10/31/oclif-node-updates"}},"content":"Back in February of this year, plans were announced to [deprecate TSLint](https://github.com/palantir/tslint/issues/4534) in favor of ESLint. TSLint\'s goal has become to work toward a \u201cunified developer experience\u201d by supporting ESLint development going forward.\\n\\n\\n\\n## What has changed in oclif\\n\\nTo keep inline with the community, oclif has transitioned to ESLint for all our core libraries as well as all our official plugins.\\n\\nStarting in v1.15.x, oclif will now optionally generate projects with ESLint for both TypeScript and JavaScript CLI\u2019s.\\n\\nESLint does require Node to be on stable LTS version, at the time of writing, Node 8.10.x, Node 10.13.x & Node 12.x.x.\\n\\n## How does this affect you\\n\\nExisting CLI\u2019s are unchanged, but any newly generated CLI\'s will only give the option of using ESLint. If you are running tslint in your CLI, we recommend you switch to ESLint as well.\\n\\nIn migrating our projects we took the following steps (for an example of these changes see this [pull request](https://github.com/oclif/githubcli/pull/10)).\\n\\n1. Install eslint\\n\\n `$ yarn add eslint eslint-config-oclif eslint-config-oclif-typescript --dev`\\n2. Add eslint related files\\n```shell\\n$ echo \'{\\n \\"extends\\": [\\n \\"oclif\\",\\n \\"oclif-typescript\\"\\n ],\\n \\"rules\\": {\\n }\\n}\' > .eslintrc\\n```\\n3. Remove tslint and related packages\\n\\n `$ yarn remove @oclif/tslint tslint`\\n4. Remove tslint related configuration files\\n\\n `$ rm tslint.json`\\n5. Change lint script in our package.json from something like:\\n\\n `\\"lint\\": \\"tsc -p test --noEmit && tslint -p test -t stylish\\"`\\n \\n to\\n \\n `\\"lint\\": \\"eslint . --ext .ts --config .eslintrc\\"`\\n\\nTo preserve the test compile (tsc -p test --noEmit) we also made the following updates to our scripts:\\n\\n`\\"pretest\\": \\"tsc -p test --noEmit\\"`\\n\\nIn some cases we had our posttest duplicating the same steps as our lint script so it\u2019s cleaner to have it reference the lint job directly with:\\n\\n`\\"posttest\\": \\"yarn lint\\"`\\n\\n\\n6. Run `yarn lint --fix`. This attempts to auto-fix any linting violations automatically. In the case an auto-fix isn\u2019t available it should be fixed manually or ignored (see the [eslint configuration doc](https://eslint.org/docs/user-guide/configuring) for more information) \\n7. Do a search in the codebase for `tslint` and remove any unnecessary tslint disabling comments, like: \\n```javascript\\n/* tslint:disable:object-literal-sort-keys */\\n```\\n\\n\\nIf you are on a version of Node that is not supported by ESLint, you will also need to update your Node engine. ESLint supports Node 8, 10, and 12 so you should upgrade to the most recent Node version compatible with your CLI and also supported by ESLint (see ESLint\'s [Installation and Usage](https://www.npmjs.com/package/eslint#installation-and-usage) instructions).\\n\\n## When will this take effect\\n\\nThese changes have taken effect in oclif v1.15.1. When you generate a new CLI or plugin it will now contain configuration for ESLint instead of TSLint."},{"id":"/2019/10/31/oclif-node-updates","metadata":{"permalink":"/blog/2019/10/31/oclif-node-updates","source":"@site/blog/2019-10-31-oclif-node-updates.md","title":"oclif\'s Current Node Support","description":"To maintain a healthy project trajectory, oclif follows and supports Node Active LTS release, currently Node 10 & Node 12. This means ensuring that oclif continues to play nice with coming Active LTS Node versions and other packages in the ecosystem. Moving forward also means leaving older versions behind. Starting in 2020, Node will stop maintaining Node 8 and it is our intent at that time to also follow suit. Let\u2019s take a look at a few ways we will be supporting these changes.","date":"2019-10-31T00:00:00.000Z","formattedDate":"October 31, 2019","tags":[],"readingTime":2.4,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"oclif\'s Current Node Support"},"unlisted":false,"prevItem":{"title":"oclif TSLint to ESLint Migration","permalink":"/blog/2019/12/05/oclif-eslint-migration"},"nextItem":{"title":"CLI Flags Explained","permalink":"/blog/2019/02/20/cli-flags-explained"}},"content":"To maintain a healthy project trajectory, oclif follows and supports [Node Active LTS release](https://nodejs.org/en/about/releases/), currently Node 10 & Node 12. This means ensuring that oclif continues to play nice with coming Active LTS Node versions and other packages in the ecosystem. Moving forward also means leaving older versions behind. Starting in 2020, Node will stop maintaining [Node 8](https://github.com/nodejs/Release#release-schedule) and it is our intent at that time to also follow suit. Let\u2019s take a look at a few ways we will be supporting these changes.\\n\\n## CI Environments\\n\\nCLIs created with the oclif cli going forward will be generated with a CircleCI configuration with Node 10 & 12 and an Appveyor configuration using Node 10. We have also added Node latest to CircleCi to be an early warning detection against coming Node changes (Node latest is managed by CircleCI).\\n\\nWe have already updated every oclif repo\'s CI configs to reflect this.\\n\\nIf your existing CLI uses either Appveyor or CircleCI you can update your config files also, like so:\\n\\n### .circleci/config.yml\\n\\nYour CircleCI config should contain a `node-latest` job, aliased as `test`. From this, there should be two extensions of this job for the Active LTS Node versions, Node 10 and Node 12.\\n\\n```\\n node-10:\\n <<: *node-latest\\n docker:\\n - image: node:10\\n node-12:\\n <<: *node-latest\\n docker:\\n - image: node:12\\n```\\n\\nNotice that these declarations only change the Docker Node images used to run that job.\\n\\nAdditionally, the jobs listed within workflows must also be updated to reflect our changes in configuration:\\n\\n```\\n jobs:\\n - node-latest\\n - node-10\\n - node-12\\n```\\n\\n### appveyor.yml\\n\\nFor appveyor we are currently only testing the oldest Active LTS Node version, Node 10. Update the `nodejs_version` proppert in your appveyor.yml file to reflect this.\\n\\n```\\nenvironment:\\n nodejs_version: \\"10\\"\\n```\\n\\n\\n## Deprecating Node 8 & Updating packge.json engines\\n\\nIn Jan 2020, Node will end its Node 8 maintenance. We will follow suit by setting the package.json engine property in oclif packages to `>=10` and bumping the package\'s major versions.\\n\\nDepending on how you ship your CLI you may wish to also bump the engines version in your CLI\'s package.json. You can read more about the implications of the engines property configuration in the [npm documentation](https://docs.npmjs.com/files/package.json#engines).\\n\\nAlso consider distributing your CLI with [its own Node version](https://oclif.io/docs/releasing#standalone-tarballs).\\n\\n## Packaged Node Version\\n\\nWhen using dev-cli to pack your CLI it will use the Node version as specified in your package.json under the `oclif.update.node.version` property. This value should reflect an Active LTS Node version (dev-cli does not currently enforce versions).\\n\\n## Supporting the future\\n\\nAs a community we may discover bumps along the way as we upgrade. If you notice something related to oclif please feel free to open an issue or submit a pull request under the relevant oclif package within [the org](https://github.com/oclif).\\n\\nWe look forward to using the latest from Node and the community and keeping oclif healthy along the way."},{"id":"/2019/02/20/cli-flags-explained","metadata":{"permalink":"/blog/2019/02/20/cli-flags-explained","source":"@site/blog/2019-02-20-cli-flags-explained.md","title":"CLI Flags Explained","description":"oclif makes it easy to create a command line interface (CLI) in node. Most commands have parameters \u2014 also known as \\"flags\\", \\"args\\", and sometimes \\"options\\". This blog post explains what these parameters are and when to use them. We also have a new feature that makes it easier for users to detect typos when using parameters.","date":"2019-02-20T00:00:00.000Z","formattedDate":"February 20, 2019","tags":[],"readingTime":4.925,"hasTruncateMarker":false,"authors":[{"name":"Casey Watts and Jeff Dickey"}],"frontMatter":{"author":"Casey Watts and Jeff Dickey","title":"CLI Flags Explained"},"unlisted":false,"prevItem":{"title":"oclif\'s Current Node Support","permalink":"/blog/2019/10/31/oclif-node-updates"},"nextItem":{"title":"Introducing oclif","permalink":"/blog/2018/03/20/introducing-oclif"}},"content":"`oclif` makes it easy to create a command line interface (CLI) in node. Most commands have **parameters** \u2014 also known as \\"flags\\", \\"args\\", and sometimes \\"options\\". This blog post explains what these parameters are and when to use them. We also have a new feature that makes it easier for users to detect typos when using parameters.\\n\\n_Note the following describes GNU-style flags. Not all CLIs follow this convention, but it is the most commonly used._\\n\\n## Parts of Speech\\n\\nAny command line interface command has a few standard \\"parts of speech\\". As a user of CLI tools, knowing these parts of speech can help you make fewer typos. It can also help you understand complex commands other people share with you more quickly. If you are designing a CLI tool it is even more important to understand these parts of speech, so you can come up with the most ergonomic interface for your users.\\n\x3c!-- DIAGRAM OF PARTS OF SPEECH EXAMPLE --\x3e\\n\\nOf the many ways you can pass data to a CLI command, three of them are **parameters** that are always to the \\"right\\" of the command. The three types of parameters are **argument**, **short flag**, and **long flag**.\\n\\n### Example `ls`\\nOne of the most common and simplest unix commands is `ls` which \\"lists\\" the contents of a directory.\\n\\n#### command\\n\\n```\\nls\\n```\\n\\nThis command `ls` works on its own, as a standalone **command**. Without any parameters this command will list the contents of the current folder, using an implied `.` directory.\\n\\n#### argument\\n\\n```\\nls .\\nls ~/code/some-repo-name\\n```\\n\\nIf you pass a command **argument** to this command, like the directory name `.` (current folder) or `~/code/some-repo-name`, it will list the contents of that directory instead.\\n\\nAn argument is anything to the right of a command that is not a flag. An argument can come before or after flags.\\n\\n#### Long flag\\nTo list additional files that are normally hidden (like `~/.bashrc`), you can use a flag on the `ls` command. `ls --all` is the **long flag** form. A long flag always uses a double dash, and it is always represented by multiple characters.\\n\\n```\\nls --all\\nls . --all\\n```\\n\\n#### Short flag\\n\\nThere is also a **short flag** form of this flag: `ls -a`. The `a` is short for `all` in this case. A short flag always uses a single dash, and it is always represented by a single letter.\\n\\n```\\nls -a\\nls . -a\\n```\\n\\nShort flags can **stack** too, so you don\'t need a separate dash for each one. Order does not matter for these, unless passing a flag argument.\\n\\n```\\nls -la\\n```\\n\\n#### Flag arguments\\nMany flags accept an **option**, which is a \\"flag argument\\" (as opposed to a \\"command argument\\"). In general a command\'s parameters can be in any order, but flags that accept options must have the option directly after the flag.\\n\\nFor an example, here the `-x` flag does not accept an option but the `-f` flag does. `archive.tar` is the option being passed to `-f`.\\n\\n```\\ntar -x -f archive.tar\\ntar -xf archive.tar\\n```\\n\\nA flag and its option can be separated by a space ` ` or an equals sign `=`. Interestingly, short flags (but not long flags) can even skip the space, although many people find it much easier to read with the space or equals sign.\\n\\nThese three are all valid and equivalent:\\n\\n```\\ntar -f archive.tar\\ntar -f=archive.tar\\ntar -farchive.tar\\n```\\n\\nLong flags must have a space or equals sign to separate the flag from its option.\\n\\n```\\ngit log --pretty=oneline\\ngit log --pretty oneline\\n```\\n\\n## Other Ways of Passing Data\\n\\nWe\'ve covered **parameters**, which are **arguments**, **short flags** and **long flags**. There are two other ways to pass data to a command: **environment variables** (\\"env vars\\"), or **standard input** (\\"stdin\\"). These won\'t be covered in this blog post.\\n\\n\\n## Designing a Command\\n\\nScenario: we want to design an oclif command that echos an input like \\"Casey\\", and returns \\"hi, Casey!\\". There are many ways the user could pass this in, and here we show an example of each type of input.\\n\\n### argument\\n\\n```\\ngreet-me Casey\\n```\\n\\n### short flag with argument\\n\\n```\\ngreet-me -n Casey\\ngreet-me -n=Casey\\ngreet-me -nCasey\\n```\\n\\n### long flag with argument\\n\\n```\\ngreet-me --name=Casey\\ngreet-me --name Casey\\n```\\n\\n### environment variable\\n\\n```\\nNAME=Casey greet-me\\n```\\n\\n### standard input\\n\\n```\\necho \\"Casey\\" | greet-me\\n```\\n\\n## Command ergonomics\\n\\n### Short flag vs long flag\\nMany CLI commands allow for both long flag and short flag forms. In the Heroku CLI every flag has at least a long flag form and roughly half of the flags also have a short flag form.\\n\\nThe long flag form is easier to read, but takes more characters to type. It is often most useful when you want someone to understand a particular command statement quickly and easily, such as in a README.\\n\\nThe short flag form is quicker to type, and is often better for frequently used commands. Short flags are especially useful when stacking short flags together.\\n\\n\\n\x3c!-- ## Did you mean?\\nIt is really easy to make a typo and use one dash instead of two, or vice versa. This \\"Long flag / short flag mismatch\\" is quite common. We hope that by catching these typos we will help you make fewer typos, save you from frustration, and speed up your development.\\n\\n`oclif` can now detect when you accidentally have the wrong number of dashes for a command, and suggest a change to the command.\\n\\n```\\nheroku config --s\\n> did you mean \\"heroku config -s\\"?\\n```\\n\\n```\\nheroku config -something-long\\n> did you mean \\"heroku config --something-long\\"?\\n```\\n\\n```\\nheroku config ---something-long\\n> did you mean to use FEWER DASHES? (something like this?)\\n```\\n\\nThis is an example of a \\"did you mean?\\" command, like this ruby plugin [did_you_mean](https://github.com/yuki24/did_you_mean).\\n--\x3e"},{"id":"/2018/03/20/introducing-oclif","metadata":{"permalink":"/blog/2018/03/20/introducing-oclif","source":"@site/blog/2018-03-20-introducing-oclif.md","title":"Introducing oclif","description":"Introducing oclif","date":"2018-03-20T00:00:00.000Z","formattedDate":"March 20, 2018","tags":[],"readingTime":0.285,"hasTruncateMarker":false,"authors":[{"name":"Jeff Dickey"}],"frontMatter":{"author":"Jeff Dickey","title":"Introducing oclif"},"unlisted":false,"prevItem":{"title":"CLI Flags Explained","permalink":"/blog/2019/02/20/cli-flags-explained"}},"content":"\\n\\nCoding for the browser takes serious time. You need to deal with front-end JS, CSS, design, product, and a ton more. On the other hand, building for a CLI takes a fraction of the effort. This makes CLIs particularly great for prototyping out new functionality, offering admin/internal tools, or power-user functionality.\\n\\nRead More"}]}')}}]); \ No newline at end of file +"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[5894],{6042:e=>{e.exports=JSON.parse('{"blogPosts":[{"id":"/2022/01/12/announcing-oclif-v2","metadata":{"permalink":"/blog/2022/01/12/announcing-oclif-v2","source":"@site/blog/2022-01-12-announcing-oclif-v2.md","title":"Announcing oclif v2!","description":"Hello and happy new year! It\'s our great pleasure to announce that we have released oclif v2, which uses the new @oclif/core library! \ud83c\udf89","date":"2022-01-12T00:00:00.000Z","formattedDate":"January 12, 2022","tags":[],"readingTime":4.48,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"Announcing oclif v2!"},"unlisted":false,"nextItem":{"title":"Introducing @oclif/core","permalink":"/blog/2021/03/01/introducing-oclif-core"}},"content":"Hello and happy new year! It\'s our great pleasure to announce that we have released oclif v2, which uses the new [@oclif/core](https://github.com/oclif/core) library! \ud83c\udf89\\n\\noclif v2 includes many changes that improve the experience of both creating and using an oclif CLI.\\n\\nGoing forward, we don\'t plan to make any updates to oclif v1 and its corresponding libraries, except for critical security fixes. See the [compatibility matrix](#compatibility-matrix) for a list of these libraries. In order to give developers time to migrate from v1 to v2, we\'re not completely dropping support yet. But at some point in the future we\'ll archive the v1 repositories and deprecate their versions on npm.\\n\\n## What\u2019s changing?\\n\\n### Repository Changes\\n\\nAll repositories under the [oclif org](https://github.com/oclif/) now use `main` as their primary branch and `oclif-v1` as the legacy branch. The `main` branch corresponds to oclif v2 and the `oclif-v1` branch to oclif v1. If you find any repos that don\u2019t have a `main` branch, you can safely assume that they\'re not used in oclif v2 and will be deprecated in the future.\\n\\n### Consolidating Tools & Libraries\\n\\nThe [`oclif-dev`](https://github.com/oclif/dev-cli) CLI has now been incorporated into [`oclif`](https://github.com/oclif/oclif). You now no longer need to install a separate package to manage your entire CLI\u2019s lifecycle.\\n\\nThe following libraries have been consolidated under [`@oclif/core`](https://github.com/oclif/core) and will be deprecated at some point in the future. Read the [migration guide](https://github.com/oclif/core/blob/main/MIGRATION.md) to learn how to update your CLI or plugin to use the new core library.\\n\\n* `@oclif/command`\\n* `@oclif/config`\\n* `@oclif/error`\\n* `@oclif/help`\\n* `@oclif/parser`\\n\\n### No more single vs multi command CLIs\\n\\nThere\'s only one \\"type\\" of oclif v2 CLI, but it can have as few or as many commands as a developer wants. As a result, there\u2019s only one command to generate CLIs, `oclif generate`, as opposed to the old `oclif single` and `oclif multi` commands.\\n\\n### Node > 12\\n\\nTo ensure oclif CLIs are as secure as possible, all v2 libraries and plugins support only Node 12 or higher as of now. Going forward, they\'ll support only Node Maintenance or higher, as defined by Node\'s release schedule here: https://nodejs.org/en/about/releases/.\\n\\n## What\u2019s new?\\n\\n### New example CLI\\n\\n[`oclif-hello-world`](https://github.com/oclif/hello-world/) is our new example repo. This is also the repo that\'s [used as a template](https://github.com/oclif/oclif/blob/edc6616e51/src/generators/cli.ts#L74) when running `oclif generate` to create a new CLI. This repo will always be able to be referenced as an example of what an oclif v2 CLI should look like.\\n\\n### Spaced commands\\n\\noclif CLIs can now use spaces, instead of colons, to separate topics and subcommands. To enable this feature, simply add `\u201ctopicSeparator\\": \\" \\"` to the oclif config in your package.json. See an example in our [example repo](https://github.com/oclif/hello-world/blob/main/package.json#L55).\\n\\n```\\n// Old commands that use :\\n$ mycli do:something\\n```\\n```\\n// New spaced commands\\n$ mycli do something\\n```\\n\\n> Note: Spaced commands are backwards compatible. So if you enable spaced commands for your CLI, users will still be able to use `:` as a separator. This ensures that any existing scripts don\'t break.\\n\\n### New Help Output\\n\\nWe\u2019ve revamped the way command help is outputted to the terminal, making it both easier to implement and easier to read. See the difference between the old help output on the left and the new help output on the right in the screenshots below.\\n\\n
| oclif v1 | \\noclif v2 | \\n
| \\n | \\n
\\n\\n### Reference material\\n\\n#### Migration Guide\\n\\nThis guide explains how to upgrade a CLI or plugin from the old oclif v1 libraries to the new `@oclif/core` library that oclif v2 uses.\\n\\nhttps://github.com/oclif/core/blob/main/MIGRATION.md\\n\\n#### Compatibility Matrix\\n\\nThe following matrix shows how the v1 libraries and plugins relate to the new v2 ones. Use this matrix as a guide to know what to drop and which versions to switch when upgrading your plugins and CLIs to v2.\\n\\n| | oclif \\"v1\\" | oclif \\"v2\\" |\\n| - | - | -|\\n| Utility CLIs | oclif@\\\\<2
@oclif/dev-cli@\\\\<2 | oclif@>=2\\n| Main packages | @oclif/command
@oclif/config
@oclif/errors
@oclif/parser
@oclif/plugin-help
| @oclif/core@>=1\\n| Node LTS | Node v8-14 | Node v12+ (at time of writing) |\\n| TypeScript | typescript@\\\\<4 | typescript@>=4 |\\n| Main plugins | @oclif/plugin-autocomplete@\\\\<1
@oclif/plugin-commands@\\\\<2
@oclif/plugin-help@\\\\<4
@oclif/plugin-not-found@\\\\<2
@oclif/plugin-plugins@\\\\<2
@oclif/plugin-update@\\\\<2
plugin-warn-if-update-available@\\\\<2
plugin-which@\\\\<2
| @oclif/plugin-autocomplete@>=1
@oclif/plugin-commands@>=2
@oclif/plugin-help@>=4
@oclif/plugin-not-found@>=2
@oclif/plugin-plugins@>=2
@oclif/plugin-update@>=2
@oclif/plugin-warn-if-update-available@>=2
@oclif/plugin-which@>=2
|"},{"id":"/2021/03/01/introducing-oclif-core","metadata":{"permalink":"/blog/2021/03/01/introducing-oclif-core","source":"@site/blog/2021-03-01-introducing-oclif-core.md","title":"Introducing @oclif/core","description":"Greetings!","date":"2021-03-01T00:00:00.000Z","formattedDate":"March 1, 2021","tags":[],"readingTime":2.18,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"Introducing @oclif/core"},"unlisted":false,"prevItem":{"title":"Announcing oclif v2!","permalink":"/blog/2022/01/12/announcing-oclif-v2"},"nextItem":{"title":"oclif Summer Update","permalink":"/blog/2020/08/26/summer-update"}},"content":"Greetings!\\n\\nWe hope this blog post finds you well.\\n\\n### Introducing...\\n\\nWe are excited to announce the next iteration of the oclif project today: `@oclif/core`.\\n\\nWe have learned a lot in the last three years of developing oclif, developing on oclif and supporting millions of command runs a day via Heroku and Salesforce CLIs.\\n`@oclif/core` (\\"Core\\") simplifies the oclif development experience and introduces highly requested new features.\\n\\nCore combines the essential oclif packages into one \\"core\\" package, aptly named `@oclif/core`.\\n\\nCore also introduces:\\n- A default command option\\n- Colon or space command syntax\\n- Async command parsing\\n- Command piping to arguments\\n\\nWith the introduction of default command functionality, Core simplifies the oclif project and removes the notion of single or multi command CLIs. Core CLIs can have 1 or many commands.\\n\\nAlong with Core, we moved the oclif-dev CLI into the oclif CLI creating a single \\"utility\\" CLI. This CLI also introduces a new AWS S3 compatible publishing scheme.\\n\\n### What to expect in the near future\\n\\nCore is in pre-release beta and being actively developed for new internal Salesforce CLIs.\\n\\nMuch documentation needs to be written in the coming months including migration paths. Migration onto Core should be as painless as possible with many exports remaining entirely unchanged. Look for forthcoming blog posts and documentation on [oclif.io](https://oclif.io).\\n\\nEarly this summer, tentively June 1, we will release Core v1. Core\'s release will coincide with major bumps to many other oclif plugin packages. See the compatibility matrix below.\\n\\nAt Core\'s v1 release, the current \\"main\\" oclif packages (namely: command, config, errors & parser) will go into maintenance mode until Jan 2022. They will receive _only_ bug and security fixes and they remain compatible with current versions of the oclif and oclif-dev CLIs. Afterwhich, they will be archived.\\n\\nCompanioning Core, the next major release of the oclif CLI (literally `oclif@2`) will generate Core CLIs.\\n\\n### Going forward\\n\\nWe are excited to release Core! We invite you to poke around the [Core repo](https://github.com/oclif/core). It may appear to be a big change but Core keeps what you already enjoy about oclif while reducing development complexity, project dependencies, package coupling and bundle size and introduces many requested features previously too prickly to weave into the current oclif architecture.\\n\\nBest,\\n\\nThe oclif team\\n\\n#### Reference: Compatibility matrix\\n\\n| | oclif \\"v1\\" | oclif \\"Core\\" |\\n| - | - | -|\\n| Utility CLIs | oclif@\\\\<2
@oclif/dev-cli@\\\\<2 | oclif@>=2\\n| Main packages | @oclif/core@\\\\<2
@oclif/config@\\\\<2
@oclif/errors@\\\\<2
@oclif/parser@\\\\<4
@oclif/plugin-help@\\\\<4
| @oclif/core@>=1\\n| Node LTS | Node v8-14 | Node v12+ |\\n| TypeScript | typescript@\\\\<4 | typescript@>=4 |\\n| Main plugins | @oclif/plugin-autocomplete@\\\\<1
@oclif/plugin-commands@\\\\<2
@oclif/plugin-help@\\\\<4
@oclif/plugin-not-found@\\\\<2
@oclif/plugin-plugins@\\\\<2
@oclif/plugin-update@\\\\<2
plugin-warn-if-update-available@\\\\<2
plugin-which@\\\\<2
| @oclif/plugin-autocomplete@>=2
@oclif/plugin-commands@>=2
@oclif/plugin-help@>=4
@oclif/plugin-not-found@>=2
@oclif/plugin-plugins@>=2
@oclif/plugin-update@>=2
@oclif/plugin-warn-if-update-available@>=2
@oclif/plugin-which@>=2
|"},{"id":"/2020/08/26/summer-update","metadata":{"permalink":"/blog/2020/08/26/summer-update","source":"@site/blog/2020-08-26-summer-update.md","title":"oclif Summer Update","description":"Hello oclif developers! We hope you are all doing well.","date":"2020-08-26T00:00:00.000Z","formattedDate":"August 26, 2020","tags":[],"readingTime":1.355,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"oclif Summer Update"},"unlisted":false,"prevItem":{"title":"Introducing @oclif/core","permalink":"/blog/2021/03/01/introducing-oclif-core"},"nextItem":{"title":"Pretty Printable Errors","permalink":"/blog/2020/07/01/pretty-printable-errors"}},"content":"Hello oclif developers! We hope you are all doing well.\\n\\nEarlier this year, we started our planning for oclifconf v2 and, like all conference, had to change course. We opted not to hold a virtual conference, however, we wanted to take some time to highlight a few oclif features shipped this year.\\n\\n## Feature: Help templating\\n\\nOne of the most requested features, help templating enables oclif developers to customize the help output for their CLI.\\n\\nRead [the announcement](/blog/introducing-custom-help-classes).\\n\\n## Feature: Custom error delegation\\n\\nThis feature both improved how oclif throws and handles errors and allows oclif developers to overwrite or interject in oclif\u2019s error handling.\\n\\nRead [the announcement](/blog/2020/07/01/pretty-printable-errors).\\n\\n## Feature: postrun hooks\\n\\nWe have added a new lifecycle event `postrun`. Your CLI can now run a hook after a command has ran.\\n\\nSee our [hook documentation](/docs/hooks).\\n\\n## Feature: Root index command\\n\\nPreviously, oclif would display CLI help if only the binary name with no command ID was invoked, oclif now supports a \\"root index\\" command. If present, a command defined at `src/commands/index.ts` will be run if no command ID is found.\\n\\n## 1 million weekly downloads\\n\\nWhile exact oclif usage metrics are hard to pin down, we use npm download statistics of oclif packages as a rough approximation. Earlier this year, oclif\'s command package hit 1 million weekly downloads for the first time!\\n\\n\\nThis year has been presented its challenges on everyone. We want to thank you, oclif developers, whom have taken the time to use and improve the oclif project. We look forward to seeing you all - in person - in the future!\\n\\nAll our best,\\n\\nThe oclif team"},{"id":"/2020/07/01/pretty-printable-errors","metadata":{"permalink":"/blog/2020/07/01/pretty-printable-errors","source":"@site/blog/2020-07-01-pretty-printable-errors.md","title":"Pretty Printable Errors","description":"Often CLIs are used as handy tools and when things go wrong it\u2019s useful to have additional context. In oclif we have added a couple of additional properties that can show extra context to the users when an error is displayed. The code, ref and suggestions will now be displayed if they are included. This will work with an existing oclif CLI by adding the latest @oclif/errors and @oclif/core to the CLI\'s package.json dependencies.","date":"2020-07-01T00:00:00.000Z","formattedDate":"July 1, 2020","tags":[],"readingTime":0.995,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"Pretty Printable Errors"},"unlisted":false,"prevItem":{"title":"oclif Summer Update","permalink":"/blog/2020/08/26/summer-update"},"nextItem":{"title":"Customizing Help in oclif","permalink":"/blog/2020/05/05/introducing-custom-help-classes"}},"content":"Often CLIs are used as handy tools and when things go wrong it\u2019s useful to have additional context. In oclif we have added a couple of additional properties that can show extra context to the users when an error is displayed. The `code`, `ref` and `suggestions` will now be displayed if they are included. This will work with an existing oclif CLI by adding the latest @oclif/errors and @oclif/core to the CLI\'s package.json dependencies.\\n\\nFor example, using `this.error` with the additional properties:\\n```js\\nclass TestError extends Command {\\n async run() {\\n this.error(\\"An error has occurred!\\", {\\n code: \\"OCLIF_ERR\\",\\n ref: \\"https://oclif.io/docs/commands#thiserrormessage-string--error-options-code-string-exit-number\\",\\n suggestions: [\\"Use these extra properties to provide additional context\\"],\\n })\\n }\\n}\\n```\\n\\nwould result with the following output:\\n```text\\n\u203a Error: An error has occurred!\\n\u203a Code: OCLIF_ERR\\n\u203a Try this: Use these extra properties to provide additional context\\n\u203a Reference: https://oclif.io/docs/commands#thiserrormessage-string--error-options-code-string-exit-number\\n```\\n\\nIf these properties are not provided then nothing changes and the CLI will continue to display the single error message output as it did before. Additionally, as part of this exercise we\u2019ve added documentation around [Error Handling in oclif](/docs/error_handling) which should come in handy if the need arises to extend oclif\u2019s default handling of errors."},{"id":"/2020/05/05/introducing-custom-help-classes","metadata":{"permalink":"/blog/2020/05/05/introducing-custom-help-classes","source":"@site/blog/2020-05-05-introducing-custom-help-classes.md","title":"Customizing Help in oclif","description":"Out of the box oclif provides a great help experience for CLIs.","date":"2020-05-05T00:00:00.000Z","formattedDate":"May 5, 2020","tags":[],"readingTime":1.67,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"Customizing Help in oclif"},"unlisted":false,"prevItem":{"title":"Pretty Printable Errors","permalink":"/blog/2020/07/01/pretty-printable-errors"},"nextItem":{"title":"oclif TSLint to ESLint Migration","permalink":"/blog/2019/12/05/oclif-eslint-migration"}},"content":"Out of the box oclif provides a great help experience for CLIs.\\n\\nBut what if, as an oclif developer, you want to customize some or all of the output?\\n\\nYou can now customize your CLI\'s help output by implementing the `HelpBase` abstract class.\\n\\n## Getting started with custom help\\n\\nIf you have not done so yet, update `@oclif/core`.\\n\\n\\n```\\n$ yarn add --latest @oclif/core\\n```\\n\\nTo get started, first define the filepath to your help class in oclif\'s config in package.json. This is a relative path to the help class, without a file extension.\\n\\nFor this example, the help class will be created in a file at \\"[project root]/src/help.ts\\".\\n\\n```\\n{\\n // ...\\n \\"oclif\\": {\\n \\"helpClass\\": \\"./lib/help\\"\\n // ...\\n }\\n // ...\\n}\\n```\\n\\nFrom here there are two paths, implement the `HelpBase` abstract class yourself or overwrite the parts of the default `Help` class you want to customize (ex: how command usage is displayed). We recommend the latter approach but cover both in the new [Help Classes docs](../../../../docs/help_classes).\\n\\n\\n## Separating TOPICS & COMMANDS in the new default `Help` class\\n\\nPreviously, topics and child commands were listed in help output under a single list heading called \\"COMMANDS\\". But we found this can be slightly confusing. Some topics are commands also (a.k.a. topic-commands) while others are simply organizational namespacing (and when ran just show their help).\\n\\nThe new default `Help` class splits the list of children into distinct lists of \\"TOPICS\\" and \\"COMMANDS\\", with the possibility of an item appearing in both if it a topic-command. This makes it clearer what is expected to be ran - \\"COMMANDS\\" - and what is providing structure - \\"TOPICS\\" - when looking at the help output.\\n\\n```\\nVERSION\\n plugin-help-example/0.0.0 darwin-x64 node-v12.12.0\\n\\nUSAGE\\n $ plugin-help-example [COMMAND]\\n\\nTOPICS\\n topic this is a topic and has child topics or commands\\n\\nCOMMANDS\\n hello describe the command here\\n help display help for plugin-help-example\\n```\\n\\nWe look forward to seeing what custom help features you implement in your oclif CLIs with this new feature!"},{"id":"/2019/12/05/oclif-eslint-migration","metadata":{"permalink":"/blog/2019/12/05/oclif-eslint-migration","source":"@site/blog/2019-12-05-oclif-eslint-migration.md","title":"oclif TSLint to ESLint Migration","description":"Back in February of this year, plans were announced to deprecate TSLint in favor of ESLint. TSLint\'s goal has become to work toward a \u201cunified developer experience\u201d by supporting ESLint development going forward.","date":"2019-12-05T00:00:00.000Z","formattedDate":"December 5, 2019","tags":[],"readingTime":2.18,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"oclif TSLint to ESLint Migration"},"unlisted":false,"prevItem":{"title":"Customizing Help in oclif","permalink":"/blog/2020/05/05/introducing-custom-help-classes"},"nextItem":{"title":"oclif\'s Current Node Support","permalink":"/blog/2019/10/31/oclif-node-updates"}},"content":"Back in February of this year, plans were announced to [deprecate TSLint](https://github.com/palantir/tslint/issues/4534) in favor of ESLint. TSLint\'s goal has become to work toward a \u201cunified developer experience\u201d by supporting ESLint development going forward.\\n\\n\\n\\n## What has changed in oclif\\n\\nTo keep inline with the community, oclif has transitioned to ESLint for all our core libraries as well as all our official plugins.\\n\\nStarting in v1.15.x, oclif will now optionally generate projects with ESLint for both TypeScript and JavaScript CLI\u2019s.\\n\\nESLint does require Node to be on stable LTS version, at the time of writing, Node 8.10.x, Node 10.13.x & Node 12.x.x.\\n\\n## How does this affect you\\n\\nExisting CLI\u2019s are unchanged, but any newly generated CLI\'s will only give the option of using ESLint. If you are running tslint in your CLI, we recommend you switch to ESLint as well.\\n\\nIn migrating our projects we took the following steps (for an example of these changes see this [pull request](https://github.com/oclif/githubcli/pull/10)).\\n\\n1. Install eslint\\n\\n `$ yarn add eslint eslint-config-oclif eslint-config-oclif-typescript --dev`\\n2. Add eslint related files\\n```shell\\n$ echo \'{\\n \\"extends\\": [\\n \\"oclif\\",\\n \\"oclif-typescript\\"\\n ],\\n \\"rules\\": {\\n }\\n}\' > .eslintrc\\n```\\n3. Remove tslint and related packages\\n\\n `$ yarn remove @oclif/tslint tslint`\\n4. Remove tslint related configuration files\\n\\n `$ rm tslint.json`\\n5. Change lint script in our package.json from something like:\\n\\n `\\"lint\\": \\"tsc -p test --noEmit && tslint -p test -t stylish\\"`\\n \\n to\\n \\n `\\"lint\\": \\"eslint . --ext .ts --config .eslintrc\\"`\\n\\nTo preserve the test compile (tsc -p test --noEmit) we also made the following updates to our scripts:\\n\\n`\\"pretest\\": \\"tsc -p test --noEmit\\"`\\n\\nIn some cases we had our posttest duplicating the same steps as our lint script so it\u2019s cleaner to have it reference the lint job directly with:\\n\\n`\\"posttest\\": \\"yarn lint\\"`\\n\\n\\n6. Run `yarn lint --fix`. This attempts to auto-fix any linting violations automatically. In the case an auto-fix isn\u2019t available it should be fixed manually or ignored (see the [eslint configuration doc](https://eslint.org/docs/user-guide/configuring) for more information) \\n7. Do a search in the codebase for `tslint` and remove any unnecessary tslint disabling comments, like: \\n```javascript\\n/* tslint:disable:object-literal-sort-keys */\\n```\\n\\n\\nIf you are on a version of Node that is not supported by ESLint, you will also need to update your Node engine. ESLint supports Node 8, 10, and 12 so you should upgrade to the most recent Node version compatible with your CLI and also supported by ESLint (see ESLint\'s [Installation and Usage](https://www.npmjs.com/package/eslint#installation-and-usage) instructions).\\n\\n## When will this take effect\\n\\nThese changes have taken effect in oclif v1.15.1. When you generate a new CLI or plugin it will now contain configuration for ESLint instead of TSLint."},{"id":"/2019/10/31/oclif-node-updates","metadata":{"permalink":"/blog/2019/10/31/oclif-node-updates","source":"@site/blog/2019-10-31-oclif-node-updates.md","title":"oclif\'s Current Node Support","description":"To maintain a healthy project trajectory, oclif follows and supports Node Active LTS release, currently Node 10 & Node 12. This means ensuring that oclif continues to play nice with coming Active LTS Node versions and other packages in the ecosystem. Moving forward also means leaving older versions behind. Starting in 2020, Node will stop maintaining Node 8 and it is our intent at that time to also follow suit. Let\u2019s take a look at a few ways we will be supporting these changes.","date":"2019-10-31T00:00:00.000Z","formattedDate":"October 31, 2019","tags":[],"readingTime":2.4,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"oclif\'s Current Node Support"},"unlisted":false,"prevItem":{"title":"oclif TSLint to ESLint Migration","permalink":"/blog/2019/12/05/oclif-eslint-migration"},"nextItem":{"title":"oclifconf 2019: A Recap","permalink":"/blog/2019/09/16/oclifconf-recap"}},"content":"To maintain a healthy project trajectory, oclif follows and supports [Node Active LTS release](https://nodejs.org/en/about/releases/), currently Node 10 & Node 12. This means ensuring that oclif continues to play nice with coming Active LTS Node versions and other packages in the ecosystem. Moving forward also means leaving older versions behind. Starting in 2020, Node will stop maintaining [Node 8](https://github.com/nodejs/Release#release-schedule) and it is our intent at that time to also follow suit. Let\u2019s take a look at a few ways we will be supporting these changes.\\n\\n## CI Environments\\n\\nCLIs created with the oclif cli going forward will be generated with a CircleCI configuration with Node 10 & 12 and an Appveyor configuration using Node 10. We have also added Node latest to CircleCi to be an early warning detection against coming Node changes (Node latest is managed by CircleCI).\\n\\nWe have already updated every oclif repo\'s CI configs to reflect this.\\n\\nIf your existing CLI uses either Appveyor or CircleCI you can update your config files also, like so:\\n\\n### .circleci/config.yml\\n\\nYour CircleCI config should contain a `node-latest` job, aliased as `test`. From this, there should be two extensions of this job for the Active LTS Node versions, Node 10 and Node 12.\\n\\n```\\n node-10:\\n <<: *node-latest\\n docker:\\n - image: node:10\\n node-12:\\n <<: *node-latest\\n docker:\\n - image: node:12\\n```\\n\\nNotice that these declarations only change the Docker Node images used to run that job.\\n\\nAdditionally, the jobs listed within workflows must also be updated to reflect our changes in configuration:\\n\\n```\\n jobs:\\n - node-latest\\n - node-10\\n - node-12\\n```\\n\\n### appveyor.yml\\n\\nFor appveyor we are currently only testing the oldest Active LTS Node version, Node 10. Update the `nodejs_version` proppert in your appveyor.yml file to reflect this.\\n\\n```\\nenvironment:\\n nodejs_version: \\"10\\"\\n```\\n\\n\\n## Deprecating Node 8 & Updating packge.json engines\\n\\nIn Jan 2020, Node will end its Node 8 maintenance. We will follow suit by setting the package.json engine property in oclif packages to `>=10` and bumping the package\'s major versions.\\n\\nDepending on how you ship your CLI you may wish to also bump the engines version in your CLI\'s package.json. You can read more about the implications of the engines property configuration in the [npm documentation](https://docs.npmjs.com/files/package.json#engines).\\n\\nAlso consider distributing your CLI with [its own Node version](https://oclif.io/docs/releasing#standalone-tarballs).\\n\\n## Packaged Node Version\\n\\nWhen using dev-cli to pack your CLI it will use the Node version as specified in your package.json under the `oclif.update.node.version` property. This value should reflect an Active LTS Node version (dev-cli does not currently enforce versions).\\n\\n## Supporting the future\\n\\nAs a community we may discover bumps along the way as we upgrade. If you notice something related to oclif please feel free to open an issue or submit a pull request under the relevant oclif package within [the org](https://github.com/oclif).\\n\\nWe look forward to using the latest from Node and the community and keeping oclif healthy along the way."},{"id":"/2019/09/16/oclifconf-recap","metadata":{"permalink":"/blog/2019/09/16/oclifconf-recap","source":"@site/blog/2019-09-16-oclifconf-recap.md","title":"oclifconf 2019: A Recap","description":"In May, Heroku and Salesforce Open Source organized oclifconf, a conference for developers & product managers building CLI tools on top of the open source oclif framework. The speakers came from various tech companies, such as Adobe, Netlify, and Apollo, who have already built amazing CLI experiences. The topics covered everything from the incredible capabilities oclif has unlocked, to the community-built plugins extending its functionality, and even what the behavior of an adaptive CLI tool might look like.","date":"2019-09-16T00:00:00.000Z","formattedDate":"September 16, 2019","tags":[],"readingTime":3.56,"hasTruncateMarker":false,"authors":[],"frontMatter":{"title":"oclifconf 2019: A Recap"},"unlisted":false,"prevItem":{"title":"oclif\'s Current Node Support","permalink":"/blog/2019/10/31/oclif-node-updates"},"nextItem":{"title":"CLI Flags Explained","permalink":"/blog/2019/02/20/cli-flags-explained"}},"content":"In May, Heroku and Salesforce Open Source organized [oclifconf](https://oclif.io/conf), a conference for developers & product managers building CLI tools on top of [the open source oclif framework](https://github.com/oclif/oclif). The speakers came from various tech companies, such as Adobe, Netlify, and Apollo, who have already built amazing CLI experiences. The topics covered everything from the incredible capabilities oclif has unlocked, to the community-built plugins extending its functionality, and even what the behavior of an adaptive CLI tool might look like.\\n\\nBelow is a listing of all of the talks from the event, along with a short summary. Enjoy!\\n\\n## The future of oclif by Jeff Dickey\\n\\n\\n\\nIn its relatively short lifetime, oclif has already inspired many developers and companies to adopt its framework as a means for implementing their own command-line tooling. In this talk, Jeff Dickey, an oclif founding team member, recaps the project\'s history and inspiration. He also looks towards the future and outlines some features and improvements that the tool could adapt. This isn\'t so much a definitive roadmap of where oclif is headed, but rather, a call to inspiration for developers eager to contribute! And if you are interested in contributing, check out the [open issues](https://github.com/oclif/oclif/issues) in the oclif GitHub repo and come say \\"Hello!\\" on [Spectrum Chat](https://spectrum.chat/oclif).\\n\\n## Open Source Citizenship by Josh Simmons\\n\\n\\n\\nWhen it comes to open source, it\'s more than just individuals now. More and more frequently, large corporations are contributing to projects by donating to contributors, sponsoring events, or upstreaming contributions. But keeping open source projects and communities healthy requires more than just money and brainpower. Josh Simmons surveyed multiple open source communities and relays his findings as to what help maintainers and contributors actually need in this talk.\\n\\n## Building an enterprise-grade CLI with oclif by Thomas Dvornik\\n\\n\\n\\nSecurity and performance are all about trust. While oclif is an extremely extensible framework for building CLI tooling, there are additional requirements to fulfill for enterprise businesses to adopt it that might not be necessary for individual developers. Thomas Dvornik outlines what he and his colleagues at Salesforce have implemented as plugins to oclif to satisfy these needs, including encrypted OAuth, plugin signing, lazy loading dependencies, synchronizing weekly releases and deprecations across dozens of repositories, and establishing cross-team coding and documentation standards.\\n\\n## How Adobe I/O built an extensible CLI with oclif by Jesse MacFadyen\\n\\n\\n\\nPerhaps oclif\'s most appealing feature is its support for plugins. In Cordova\'s case, they\'ve created a sophisticated telemetry system that helps Adobe developers see which commands users are using--and reports on which ones are erroring out. By embedding a feedback system into the tool, users are even able to quickly send their suggestions to a form, without ever leaving the terminal. Jesse MacFadyen demonstrates how oclif\'s plugin system can work beyond simply executing commands.\\n\\n## Integrating oclif with GraphQL and Apollo by Evans Hauser\\n\\n\\n\\nFor Evans Hauser and the team at Apollo, oclif is best thought of as \\"React for the CLI.\\" As a client paired with a strongly-typed API contract to a server, it can deliver structured and consistent commands to retrieve external data. What better mechanism to use for this transfer than GraphQL, a framework which empowers the client to ask precisely for the data it needs, and nothing more?\\n\\n## Adaptive Intent-based CLI State Machines by Shawn Wang\\n\\n\\n\\nIn designing oclif, [Jeff Dickey wrote out 12 CLI factors to keep in mind](https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46). In this talk, Shawn Wang outlines a 13th: state. State is hard, because it depends on context, and context depends on understanding what a user intends to do, not what they are asking. Shawn is working towards enabling oclif to better understand the commands a user has entered, so that it can predict and interpret future commands that might be entered next. This would enable CLI tools to not just interpret a users\' commands, but to also interpret their intent."},{"id":"/2019/02/20/cli-flags-explained","metadata":{"permalink":"/blog/2019/02/20/cli-flags-explained","source":"@site/blog/2019-02-20-cli-flags-explained.md","title":"CLI Flags Explained","description":"oclif makes it easy to create a command line interface (CLI) in node. Most commands have parameters \u2014 also known as \\"flags\\", \\"args\\", and sometimes \\"options\\". This blog post explains what these parameters are and when to use them. We also have a new feature that makes it easier for users to detect typos when using parameters.","date":"2019-02-20T00:00:00.000Z","formattedDate":"February 20, 2019","tags":[],"readingTime":4.925,"hasTruncateMarker":false,"authors":[{"name":"Casey Watts and Jeff Dickey"}],"frontMatter":{"author":"Casey Watts and Jeff Dickey","title":"CLI Flags Explained"},"unlisted":false,"prevItem":{"title":"oclifconf 2019: A Recap","permalink":"/blog/2019/09/16/oclifconf-recap"},"nextItem":{"title":"Introducing oclif","permalink":"/blog/2018/03/20/introducing-oclif"}},"content":"`oclif` makes it easy to create a command line interface (CLI) in node. Most commands have **parameters** \u2014 also known as \\"flags\\", \\"args\\", and sometimes \\"options\\". This blog post explains what these parameters are and when to use them. We also have a new feature that makes it easier for users to detect typos when using parameters.\\n\\n_Note the following describes GNU-style flags. Not all CLIs follow this convention, but it is the most commonly used._\\n\\n## Parts of Speech\\n\\nAny command line interface command has a few standard \\"parts of speech\\". As a user of CLI tools, knowing these parts of speech can help you make fewer typos. It can also help you understand complex commands other people share with you more quickly. If you are designing a CLI tool it is even more important to understand these parts of speech, so you can come up with the most ergonomic interface for your users.\\n\x3c!-- DIAGRAM OF PARTS OF SPEECH EXAMPLE --\x3e\\n\\nOf the many ways you can pass data to a CLI command, three of them are **parameters** that are always to the \\"right\\" of the command. The three types of parameters are **argument**, **short flag**, and **long flag**.\\n\\n### Example `ls`\\nOne of the most common and simplest unix commands is `ls` which \\"lists\\" the contents of a directory.\\n\\n#### command\\n\\n```\\nls\\n```\\n\\nThis command `ls` works on its own, as a standalone **command**. Without any parameters this command will list the contents of the current folder, using an implied `.` directory.\\n\\n#### argument\\n\\n```\\nls .\\nls ~/code/some-repo-name\\n```\\n\\nIf you pass a command **argument** to this command, like the directory name `.` (current folder) or `~/code/some-repo-name`, it will list the contents of that directory instead.\\n\\nAn argument is anything to the right of a command that is not a flag. An argument can come before or after flags.\\n\\n#### Long flag\\nTo list additional files that are normally hidden (like `~/.bashrc`), you can use a flag on the `ls` command. `ls --all` is the **long flag** form. A long flag always uses a double dash, and it is always represented by multiple characters.\\n\\n```\\nls --all\\nls . --all\\n```\\n\\n#### Short flag\\n\\nThere is also a **short flag** form of this flag: `ls -a`. The `a` is short for `all` in this case. A short flag always uses a single dash, and it is always represented by a single letter.\\n\\n```\\nls -a\\nls . -a\\n```\\n\\nShort flags can **stack** too, so you don\'t need a separate dash for each one. Order does not matter for these, unless passing a flag argument.\\n\\n```\\nls -la\\n```\\n\\n#### Flag arguments\\nMany flags accept an **option**, which is a \\"flag argument\\" (as opposed to a \\"command argument\\"). In general a command\'s parameters can be in any order, but flags that accept options must have the option directly after the flag.\\n\\nFor an example, here the `-x` flag does not accept an option but the `-f` flag does. `archive.tar` is the option being passed to `-f`.\\n\\n```\\ntar -x -f archive.tar\\ntar -xf archive.tar\\n```\\n\\nA flag and its option can be separated by a space ` ` or an equals sign `=`. Interestingly, short flags (but not long flags) can even skip the space, although many people find it much easier to read with the space or equals sign.\\n\\nThese three are all valid and equivalent:\\n\\n```\\ntar -f archive.tar\\ntar -f=archive.tar\\ntar -farchive.tar\\n```\\n\\nLong flags must have a space or equals sign to separate the flag from its option.\\n\\n```\\ngit log --pretty=oneline\\ngit log --pretty oneline\\n```\\n\\n## Other Ways of Passing Data\\n\\nWe\'ve covered **parameters**, which are **arguments**, **short flags** and **long flags**. There are two other ways to pass data to a command: **environment variables** (\\"env vars\\"), or **standard input** (\\"stdin\\"). These won\'t be covered in this blog post.\\n\\n\\n## Designing a Command\\n\\nScenario: we want to design an oclif command that echos an input like \\"Casey\\", and returns \\"hi, Casey!\\". There are many ways the user could pass this in, and here we show an example of each type of input.\\n\\n### argument\\n\\n```\\ngreet-me Casey\\n```\\n\\n### short flag with argument\\n\\n```\\ngreet-me -n Casey\\ngreet-me -n=Casey\\ngreet-me -nCasey\\n```\\n\\n### long flag with argument\\n\\n```\\ngreet-me --name=Casey\\ngreet-me --name Casey\\n```\\n\\n### environment variable\\n\\n```\\nNAME=Casey greet-me\\n```\\n\\n### standard input\\n\\n```\\necho \\"Casey\\" | greet-me\\n```\\n\\n## Command ergonomics\\n\\n### Short flag vs long flag\\nMany CLI commands allow for both long flag and short flag forms. In the Heroku CLI every flag has at least a long flag form and roughly half of the flags also have a short flag form.\\n\\nThe long flag form is easier to read, but takes more characters to type. It is often most useful when you want someone to understand a particular command statement quickly and easily, such as in a README.\\n\\nThe short flag form is quicker to type, and is often better for frequently used commands. Short flags are especially useful when stacking short flags together.\\n\\n\\n\x3c!-- ## Did you mean?\\nIt is really easy to make a typo and use one dash instead of two, or vice versa. This \\"Long flag / short flag mismatch\\" is quite common. We hope that by catching these typos we will help you make fewer typos, save you from frustration, and speed up your development.\\n\\n`oclif` can now detect when you accidentally have the wrong number of dashes for a command, and suggest a change to the command.\\n\\n```\\nheroku config --s\\n> did you mean \\"heroku config -s\\"?\\n```\\n\\n```\\nheroku config -something-long\\n> did you mean \\"heroku config --something-long\\"?\\n```\\n\\n```\\nheroku config ---something-long\\n> did you mean to use FEWER DASHES? (something like this?)\\n```\\n\\nThis is an example of a \\"did you mean?\\" command, like this ruby plugin [did_you_mean](https://github.com/yuki24/did_you_mean).\\n--\x3e"},{"id":"/2018/03/20/introducing-oclif","metadata":{"permalink":"/blog/2018/03/20/introducing-oclif","source":"@site/blog/2018-03-20-introducing-oclif.md","title":"Introducing oclif","description":"Introducing oclif","date":"2018-03-20T00:00:00.000Z","formattedDate":"March 20, 2018","tags":[],"readingTime":0.285,"hasTruncateMarker":false,"authors":[{"name":"Jeff Dickey"}],"frontMatter":{"author":"Jeff Dickey","title":"Introducing oclif"},"unlisted":false,"prevItem":{"title":"CLI Flags Explained","permalink":"/blog/2019/02/20/cli-flags-explained"}},"content":"\\n\\nCoding for the browser takes serious time. You need to deal with front-end JS, CSS, design, product, and a ton more. On the other hand, building for a CLI takes a fraction of the effort. This makes CLIs particularly great for prototyping out new functionality, offering admin/internal tools, or power-user functionality.\\n\\nRead More"}]}')}}]); \ No newline at end of file diff --git a/assets/js/b3cc73c6.b180e5dd.js b/assets/js/b3cc73c6.df88c55c.js similarity index 99% rename from assets/js/b3cc73c6.b180e5dd.js rename to assets/js/b3cc73c6.df88c55c.js index 02a27525..d59e463e 100644 --- a/assets/js/b3cc73c6.b180e5dd.js +++ b/assets/js/b3cc73c6.df88c55c.js @@ -1 +1 @@ -"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[2381],{6957:(e,o,s)=>{s.r(o),s.d(o,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>i,metadata:()=>a,toc:()=>c});var n=s(4848),t=s(8453);const i={title:"How We Work"},r=void 0,a={id:"how_we_work",title:"How We Work",description:"oclif is an open-source project built and maintained by Salesforce and an essential component of Salesforce's developer experiences, powering millions of users' CLIs a day via the Salesforce CLI, the Heroku CLI and others.",source:"@site/../docs/how_we_work.md",sourceDirName:".",slug:"/how_we_work",permalink:"/docs/how_we_work",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/how_we_work.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711121897,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"How We Work"},sidebar:"docs",previous:{title:"Related Repositories",permalink:"/docs/related_repos"},next:{title:"Feedback",permalink:"/docs/feedback"}},l={},c=[{value:"Code of Conduct & Community Guidelines",id:"code-of-conduct--community-guidelines",level:2},{value:"Work Tracking",id:"work-tracking",level:2},{value:"Issues",id:"issues",level:2},{value:"Pull Requests",id:"pull-requests",level:2},{value:"Deprecations",id:"deprecations",level:2},{value:"Blog Posts",id:"blog-posts",level:2},{value:"Feedback",id:"feedback",level:2},{value:"Updates to How We Work",id:"updates-to-how-we-work",level:2}];function d(e){const o={a:"a",h2:"h2",li:"li",p:"p",ul:"ul",...(0,t.R)(),...e.components};return(0,n.jsxs)(n.Fragment,{children:[(0,n.jsxs)(o.p,{children:["oclif is an open-source project built and maintained by Salesforce and an essential component of Salesforce's developer experiences, powering millions of users' CLIs a day via the Salesforce CLI, the Heroku CLI and ",(0,n.jsx)(o.a,{href:"https://www.npmjs.com/browse/depended/@oclif/core",children:"others"}),"."]}),"\n",(0,n.jsxs)(o.p,{children:["As an open-source project, ",(0,n.jsx)(o.a,{href:"https://github.com/oclif",children:"oclif repos live on GitHub"})," and are published to ",(0,n.jsx)(o.a,{href:"https://www.npmjs.com/search?q=oclif",children:"npmjs.com"}),"."]}),"\n",(0,n.jsx)(o.h2,{id:"code-of-conduct--community-guidelines",children:"Code of Conduct & Community Guidelines"}),"\n",(0,n.jsxs)(o.p,{children:["We are thrilled to offer oclif as open-source. As such, please review our project ",(0,n.jsx)(o.a,{href:"https://github.com/salesforce/oss-template/blob/master/CODE_OF_CONDUCT.md",children:"Code of Conduct"}),". If you have any questions or concerns, please ",(0,n.jsx)(o.a,{href:"/docs/feedback",children:"contact us"}),"."]}),"\n",(0,n.jsx)(o.h2,{id:"work-tracking",children:"Work Tracking"}),"\n",(0,n.jsxs)(o.p,{children:["We use a ",(0,n.jsx)(o.a,{href:"https://github.com/orgs/oclif/projects/1",children:"GitHub Project board"})," to manage our work across all oclif repos. This board is used kanban style, in which, cards (i.e. work items) move left to right as they progress towards \u201cDone\u201d and higher priority cards sit towards the top of the columns, with lower priority cards sitting further below."]}),"\n",(0,n.jsx)(o.h2,{id:"issues",children:"Issues"}),"\n",(0,n.jsxs)(o.p,{children:["Issues are made in their corresponding repo as appropriate. If you are unsure which repo an issue might belong to, make an ",(0,n.jsx)(o.a,{href:"https://github.com/oclif/oclif/issues",children:"issue in the oclif repo"}),"."]}),"\n",(0,n.jsx)(o.p,{children:"We triage issues as we can, usually with a week of when it was created (unfortunately, we can make no commitment to when an issue will be triaged)."}),"\n",(0,n.jsx)(o.p,{children:"Issues triaged by an our team will be marked with one of the following labels :"}),"\n",(0,n.jsxs)(o.ul,{children:["\n",(0,n.jsx)(o.li,{children:"\u201cbug\u201d"}),"\n",(0,n.jsx)(o.li,{children:"\u201cenhancement\u201d"}),"\n",(0,n.jsx)(o.li,{children:"\u201cdocs\u201d"}),"\n",(0,n.jsx)(o.li,{children:"\u201cwont-fix\u201d"}),"\n",(0,n.jsx)(o.li,{children:"\u201cinvalid\u201d"}),"\n",(0,n.jsx)(o.li,{children:"\u201cduplicate\u201d"}),"\n"]}),"\n",(0,n.jsx)(o.p,{children:"An issue will be considered stale after a month has passed with no further feedback or input from the author after input from an oclif team member. Stale issues will be notified with a comment of its stale state and any actions needed to take to keep it alive."}),"\n",(0,n.jsx)(o.p,{children:"An issue will be closed if:"}),"\n",(0,n.jsxs)(o.ul,{children:["\n",(0,n.jsx)(o.li,{children:"It has been fixed via a PR"}),"\n",(0,n.jsx)(o.li,{children:"Has a \u201cwont-fix\u201d, \u201cinvalid\u201d or \u201cduplicate\u201d label"}),"\n",(0,n.jsx)(o.li,{children:"A week has passed after a stale issue notification has been posted with no further feedback or input from the author"}),"\n"]}),"\n",(0,n.jsx)(o.h2,{id:"pull-requests",children:"Pull Requests"}),"\n",(0,n.jsx)(o.p,{children:"We review repo PRs as we can, usually with two weeks of when it was created (unfortunately, we can make no commitment to when a PR will be reviewed)."}),"\n",(0,n.jsx)(o.p,{children:"PRs reviewers may seek additional changes or clarifying input from the author as appropriate."}),"\n",(0,n.jsx)(o.p,{children:"Note: It is often more conducive to first open an issue and solicit feedback on possible solutions for your PR. We hate to see PR\u2019s we don\u2019t end up accepting and this helps to avoid that!"}),"\n",(0,n.jsx)(o.p,{children:"A PR will be considered stale after a month has passed with no further feedback or input from the author after input from an oclif team member. Stale PRs will be notified with a comment of its stale state and any actions needed to take to keep it alive."}),"\n",(0,n.jsx)(o.p,{children:"A PR will be closed if:"}),"\n",(0,n.jsxs)(o.ul,{children:["\n",(0,n.jsx)(o.li,{children:"It has been merged"}),"\n",(0,n.jsx)(o.li,{children:"After a dialogue with the author informing them why the PR cannot be accepted"}),"\n",(0,n.jsx)(o.li,{children:"A week has passed after a stale PR notification has been posted with no further feedback or input from the author"}),"\n"]}),"\n",(0,n.jsx)(o.h2,{id:"deprecations",children:"Deprecations"}),"\n",(0,n.jsx)(o.p,{children:"oclif packages follow semantic versioning and therefore only deprecate features in new major version releases."}),"\n",(0,n.jsx)(o.p,{children:"In the exceptional case a deprecation needs to happen outside a new major version, we will notify users via our blog or, as appropriate, with deprecation warnings in the tooling itself."}),"\n",(0,n.jsx)(o.h2,{id:"blog-posts",children:"Blog Posts"}),"\n",(0,n.jsxs)(o.p,{children:["We aim to announce most features via ",(0,n.jsx)(o.a,{href:"/blog",children:"our blog"}),". Be sure to check back regularly to see new announcements!"]}),"\n",(0,n.jsx)(o.h2,{id:"feedback",children:"Feedback"}),"\n",(0,n.jsxs)(o.p,{children:["See our ",(0,n.jsx)(o.a,{href:"/docs/feedback",children:"Feedback page"}),"."]}),"\n",(0,n.jsx)(o.h2,{id:"updates-to-how-we-work",children:"Updates to How We Work"}),"\n",(0,n.jsx)(o.p,{children:"Please check back periodically to review any updates to this page."})]})}function h(e={}){const{wrapper:o}={...(0,t.R)(),...e.components};return o?(0,n.jsx)(o,{...e,children:(0,n.jsx)(d,{...e})}):d(e)}},8453:(e,o,s)=>{s.d(o,{R:()=>r,x:()=>a});var n=s(6540);const t={},i=n.createContext(t);function r(e){const o=n.useContext(i);return n.useMemo((function(){return"function"==typeof e?e(o):{...o,...e}}),[o,e])}function a(e){let o;return o=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:r(e.components),n.createElement(i.Provider,{value:o},e.children)}}}]); \ No newline at end of file +"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[2381],{6957:(e,o,s)=>{s.r(o),s.d(o,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>i,metadata:()=>a,toc:()=>c});var n=s(4848),t=s(8453);const i={title:"How We Work"},r=void 0,a={id:"how_we_work",title:"How We Work",description:"oclif is an open-source project built and maintained by Salesforce and an essential component of Salesforce's developer experiences, powering millions of users' CLIs a day via the Salesforce CLI, the Heroku CLI and others.",source:"@site/../docs/how_we_work.md",sourceDirName:".",slug:"/how_we_work",permalink:"/docs/how_we_work",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/how_we_work.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711137687,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"How We Work"},sidebar:"docs",previous:{title:"Related Repositories",permalink:"/docs/related_repos"},next:{title:"Feedback",permalink:"/docs/feedback"}},l={},c=[{value:"Code of Conduct & Community Guidelines",id:"code-of-conduct--community-guidelines",level:2},{value:"Work Tracking",id:"work-tracking",level:2},{value:"Issues",id:"issues",level:2},{value:"Pull Requests",id:"pull-requests",level:2},{value:"Deprecations",id:"deprecations",level:2},{value:"Blog Posts",id:"blog-posts",level:2},{value:"Feedback",id:"feedback",level:2},{value:"Updates to How We Work",id:"updates-to-how-we-work",level:2}];function d(e){const o={a:"a",h2:"h2",li:"li",p:"p",ul:"ul",...(0,t.R)(),...e.components};return(0,n.jsxs)(n.Fragment,{children:[(0,n.jsxs)(o.p,{children:["oclif is an open-source project built and maintained by Salesforce and an essential component of Salesforce's developer experiences, powering millions of users' CLIs a day via the Salesforce CLI, the Heroku CLI and ",(0,n.jsx)(o.a,{href:"https://www.npmjs.com/browse/depended/@oclif/core",children:"others"}),"."]}),"\n",(0,n.jsxs)(o.p,{children:["As an open-source project, ",(0,n.jsx)(o.a,{href:"https://github.com/oclif",children:"oclif repos live on GitHub"})," and are published to ",(0,n.jsx)(o.a,{href:"https://www.npmjs.com/search?q=oclif",children:"npmjs.com"}),"."]}),"\n",(0,n.jsx)(o.h2,{id:"code-of-conduct--community-guidelines",children:"Code of Conduct & Community Guidelines"}),"\n",(0,n.jsxs)(o.p,{children:["We are thrilled to offer oclif as open-source. As such, please review our project ",(0,n.jsx)(o.a,{href:"https://github.com/salesforce/oss-template/blob/master/CODE_OF_CONDUCT.md",children:"Code of Conduct"}),". If you have any questions or concerns, please ",(0,n.jsx)(o.a,{href:"/docs/feedback",children:"contact us"}),"."]}),"\n",(0,n.jsx)(o.h2,{id:"work-tracking",children:"Work Tracking"}),"\n",(0,n.jsxs)(o.p,{children:["We use a ",(0,n.jsx)(o.a,{href:"https://github.com/orgs/oclif/projects/1",children:"GitHub Project board"})," to manage our work across all oclif repos. This board is used kanban style, in which, cards (i.e. work items) move left to right as they progress towards \u201cDone\u201d and higher priority cards sit towards the top of the columns, with lower priority cards sitting further below."]}),"\n",(0,n.jsx)(o.h2,{id:"issues",children:"Issues"}),"\n",(0,n.jsxs)(o.p,{children:["Issues are made in their corresponding repo as appropriate. If you are unsure which repo an issue might belong to, make an ",(0,n.jsx)(o.a,{href:"https://github.com/oclif/oclif/issues",children:"issue in the oclif repo"}),"."]}),"\n",(0,n.jsx)(o.p,{children:"We triage issues as we can, usually with a week of when it was created (unfortunately, we can make no commitment to when an issue will be triaged)."}),"\n",(0,n.jsx)(o.p,{children:"Issues triaged by an our team will be marked with one of the following labels :"}),"\n",(0,n.jsxs)(o.ul,{children:["\n",(0,n.jsx)(o.li,{children:"\u201cbug\u201d"}),"\n",(0,n.jsx)(o.li,{children:"\u201cenhancement\u201d"}),"\n",(0,n.jsx)(o.li,{children:"\u201cdocs\u201d"}),"\n",(0,n.jsx)(o.li,{children:"\u201cwont-fix\u201d"}),"\n",(0,n.jsx)(o.li,{children:"\u201cinvalid\u201d"}),"\n",(0,n.jsx)(o.li,{children:"\u201cduplicate\u201d"}),"\n"]}),"\n",(0,n.jsx)(o.p,{children:"An issue will be considered stale after a month has passed with no further feedback or input from the author after input from an oclif team member. Stale issues will be notified with a comment of its stale state and any actions needed to take to keep it alive."}),"\n",(0,n.jsx)(o.p,{children:"An issue will be closed if:"}),"\n",(0,n.jsxs)(o.ul,{children:["\n",(0,n.jsx)(o.li,{children:"It has been fixed via a PR"}),"\n",(0,n.jsx)(o.li,{children:"Has a \u201cwont-fix\u201d, \u201cinvalid\u201d or \u201cduplicate\u201d label"}),"\n",(0,n.jsx)(o.li,{children:"A week has passed after a stale issue notification has been posted with no further feedback or input from the author"}),"\n"]}),"\n",(0,n.jsx)(o.h2,{id:"pull-requests",children:"Pull Requests"}),"\n",(0,n.jsx)(o.p,{children:"We review repo PRs as we can, usually with two weeks of when it was created (unfortunately, we can make no commitment to when a PR will be reviewed)."}),"\n",(0,n.jsx)(o.p,{children:"PRs reviewers may seek additional changes or clarifying input from the author as appropriate."}),"\n",(0,n.jsx)(o.p,{children:"Note: It is often more conducive to first open an issue and solicit feedback on possible solutions for your PR. We hate to see PR\u2019s we don\u2019t end up accepting and this helps to avoid that!"}),"\n",(0,n.jsx)(o.p,{children:"A PR will be considered stale after a month has passed with no further feedback or input from the author after input from an oclif team member. Stale PRs will be notified with a comment of its stale state and any actions needed to take to keep it alive."}),"\n",(0,n.jsx)(o.p,{children:"A PR will be closed if:"}),"\n",(0,n.jsxs)(o.ul,{children:["\n",(0,n.jsx)(o.li,{children:"It has been merged"}),"\n",(0,n.jsx)(o.li,{children:"After a dialogue with the author informing them why the PR cannot be accepted"}),"\n",(0,n.jsx)(o.li,{children:"A week has passed after a stale PR notification has been posted with no further feedback or input from the author"}),"\n"]}),"\n",(0,n.jsx)(o.h2,{id:"deprecations",children:"Deprecations"}),"\n",(0,n.jsx)(o.p,{children:"oclif packages follow semantic versioning and therefore only deprecate features in new major version releases."}),"\n",(0,n.jsx)(o.p,{children:"In the exceptional case a deprecation needs to happen outside a new major version, we will notify users via our blog or, as appropriate, with deprecation warnings in the tooling itself."}),"\n",(0,n.jsx)(o.h2,{id:"blog-posts",children:"Blog Posts"}),"\n",(0,n.jsxs)(o.p,{children:["We aim to announce most features via ",(0,n.jsx)(o.a,{href:"/blog",children:"our blog"}),". Be sure to check back regularly to see new announcements!"]}),"\n",(0,n.jsx)(o.h2,{id:"feedback",children:"Feedback"}),"\n",(0,n.jsxs)(o.p,{children:["See our ",(0,n.jsx)(o.a,{href:"/docs/feedback",children:"Feedback page"}),"."]}),"\n",(0,n.jsx)(o.h2,{id:"updates-to-how-we-work",children:"Updates to How We Work"}),"\n",(0,n.jsx)(o.p,{children:"Please check back periodically to review any updates to this page."})]})}function h(e={}){const{wrapper:o}={...(0,t.R)(),...e.components};return o?(0,n.jsx)(o,{...e,children:(0,n.jsx)(d,{...e})}):d(e)}},8453:(e,o,s)=>{s.d(o,{R:()=>r,x:()=>a});var n=s(6540);const t={},i=n.createContext(t);function r(e){const o=n.useContext(i);return n.useMemo((function(){return"function"==typeof e?e(o):{...o,...e}}),[o,e])}function a(e){let o;return o=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:r(e.components),n.createElement(i.Provider,{value:o},e.children)}}}]); \ No newline at end of file diff --git a/assets/js/b4a95747.8bdd8694.js b/assets/js/b4a95747.988010fc.js similarity index 97% rename from assets/js/b4a95747.8bdd8694.js rename to assets/js/b4a95747.988010fc.js index a285b145..a8f849e0 100644 --- a/assets/js/b4a95747.8bdd8694.js +++ b/assets/js/b4a95747.988010fc.js @@ -1 +1 @@ -"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[8908],{3424:(e,n,o)=>{o.r(n),o.d(n,{assets:()=>a,contentTitle:()=>r,default:()=>u,frontMatter:()=>l,metadata:()=>c,toc:()=>i});var t=o(4848),s=o(8453);const l={title:"JSON"},r=void 0,c={id:"json",title:"JSON",description:"If you want to use the --json flag to return JSON output to the user, then you can set the enableJsonFlag property on the Command class.",source:"@site/../docs/json.md",sourceDirName:".",slug:"/json",permalink:"/docs/json",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/json.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711121897,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"JSON"},sidebar:"docs",previous:{title:"Error Handling",permalink:"/docs/error_handling"},next:{title:"Release",permalink:"/docs/releasing"}},a={},i=[];function d(e){const n={code:"code",p:"p",pre:"pre",strong:"strong",...(0,s.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsxs)(n.p,{children:["If you want to use the ",(0,t.jsx)(n.code,{children:"--json"})," flag to return JSON output to the user, then you can set the ",(0,t.jsx)(n.code,{children:"enableJsonFlag"})," property on the ",(0,t.jsx)(n.code,{children:"Command"})," class."]}),"\n",(0,t.jsxs)(n.p,{children:["When this property is set and the user supplies the ",(0,t.jsx)(n.code,{children:"--json"})," flag, the command will suppress all logs and instead log the return value to the console in JSON format. ",(0,t.jsx)(n.strong,{children:"Note"})," log suppression will only work if you use the logging methods on the ",(0,t.jsx)(n.code,{children:"Command"})," class instance. In other words, ",(0,t.jsx)(n.code,{children:"this.log"})," will be automatically suppressed but ",(0,t.jsx)(n.code,{children:"console.log"})," will not be."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"import {Command} from '@oclif/core'\nexport class HelloCommand extends Command {\n public static enableJsonFlag = true\n public async run(): Promise<{ message: string }> {\n console.log('hello, world!')\n return { message: 'hello, world!' }\n }\n}\n\n"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"$ my-cli hello\nhello, world!\n"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'$ my-cli hello --json\n{\n "message": "hello, world!"\n}\n'})})]})}function u(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},8453:(e,n,o)=>{o.d(n,{R:()=>r,x:()=>c});var t=o(6540);const s={},l=t.createContext(s);function r(e){const n=t.useContext(l);return t.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:r(e.components),t.createElement(l.Provider,{value:n},e.children)}}}]); \ No newline at end of file +"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[8908],{3424:(e,n,o)=>{o.r(n),o.d(n,{assets:()=>a,contentTitle:()=>r,default:()=>u,frontMatter:()=>l,metadata:()=>c,toc:()=>i});var t=o(4848),s=o(8453);const l={title:"JSON"},r=void 0,c={id:"json",title:"JSON",description:"If you want to use the --json flag to return JSON output to the user, then you can set the enableJsonFlag property on the Command class.",source:"@site/../docs/json.md",sourceDirName:".",slug:"/json",permalink:"/docs/json",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/json.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711137687,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"JSON"},sidebar:"docs",previous:{title:"Error Handling",permalink:"/docs/error_handling"},next:{title:"Release",permalink:"/docs/releasing"}},a={},i=[];function d(e){const n={code:"code",p:"p",pre:"pre",strong:"strong",...(0,s.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsxs)(n.p,{children:["If you want to use the ",(0,t.jsx)(n.code,{children:"--json"})," flag to return JSON output to the user, then you can set the ",(0,t.jsx)(n.code,{children:"enableJsonFlag"})," property on the ",(0,t.jsx)(n.code,{children:"Command"})," class."]}),"\n",(0,t.jsxs)(n.p,{children:["When this property is set and the user supplies the ",(0,t.jsx)(n.code,{children:"--json"})," flag, the command will suppress all logs and instead log the return value to the console in JSON format. ",(0,t.jsx)(n.strong,{children:"Note"})," log suppression will only work if you use the logging methods on the ",(0,t.jsx)(n.code,{children:"Command"})," class instance. In other words, ",(0,t.jsx)(n.code,{children:"this.log"})," will be automatically suppressed but ",(0,t.jsx)(n.code,{children:"console.log"})," will not be."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"import {Command} from '@oclif/core'\nexport class HelloCommand extends Command {\n public static enableJsonFlag = true\n public async run(): Promise<{ message: string }> {\n console.log('hello, world!')\n return { message: 'hello, world!' }\n }\n}\n\n"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"$ my-cli hello\nhello, world!\n"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:'$ my-cli hello --json\n{\n "message": "hello, world!"\n}\n'})})]})}function u(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},8453:(e,n,o)=>{o.d(n,{R:()=>r,x:()=>c});var t=o(6540);const s={},l=t.createContext(s);function r(e){const n=t.useContext(l);return t.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:r(e.components),t.createElement(l.Provider,{value:n},e.children)}}}]); \ No newline at end of file diff --git a/assets/js/c5890d18.1f021986.js b/assets/js/c5890d18.8cdbbe0c.js similarity index 99% rename from assets/js/c5890d18.1f021986.js rename to assets/js/c5890d18.8cdbbe0c.js index 07124313..b52f82a3 100644 --- a/assets/js/c5890d18.1f021986.js +++ b/assets/js/c5890d18.8cdbbe0c.js @@ -1 +1 @@ -"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[5069],{1588:(e,n,s)=>{s.r(n),s.d(n,{assets:()=>d,contentTitle:()=>l,default:()=>a,frontMatter:()=>o,metadata:()=>r,toc:()=>c});var t=s(4848),i=s(8453);const o={title:"Themes"},l=void 0,r={id:"themes",title:"Themes",description:"oclif supports themes that users can either define for themselves or select from a variety of themes you ship with your CLI.",source:"@site/../docs/themes.md",sourceDirName:".",slug:"/themes",permalink:"/docs/themes",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/themes.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711121897,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Themes"},sidebar:"docs",previous:{title:"ESM",permalink:"/docs/esm"},next:{title:"Examples",permalink:"/docs/examples"}},d={},c=[{value:"theme.json",id:"themejson",level:2},{value:"Supported Theme Properties",id:"supported-theme-properties",level:3},{value:"Disabling Themes",id:"disabling-themes",level:2},{value:"Extending Themes",id:"extending-themes",level:2}];function h(e){const n={a:"a",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",ul:"ul",...(0,i.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.p,{children:"oclif supports themes that users can either define for themselves or select from a variety of themes you ship with your CLI."}),"\n",(0,t.jsxs)(n.p,{children:["By default, the theme only applies to help output but you can extend the theme for your own purposes if you want. See ",(0,t.jsx)(n.a,{href:"#extending-themes",children:"Extending Themes"})," section below."]}),"\n",(0,t.jsx)(n.h2,{id:"themejson",children:"theme.json"}),"\n",(0,t.jsxs)(n.p,{children:["By default oclif will read themes from ",(0,t.jsx)(n.code,{children:"~/.config/
HelpBase class",id:"extending-the-helpbase-class",level:2},{value:"Extending the default Help class",id:"extending-the-default-help-class",level:2},{value:"Building custom help classes in JavaScript projects",id:"building-custom-help-classes-in-javascript-projects",level:2}];function d(e){const n={a:"a",code:"code",h2:"h2",p:"p",pre:"pre",...(0,l.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsxs)(n.p,{children:["Out of the box oclif provides a great help experience for CLIs. Users can invoke help with the ",(0,s.jsx)(n.code,{children:"--help"})," flag."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"$ my-cli login --help\n"})}),"\n",(0,s.jsxs)(n.p,{children:["If you want your CLI to have an explicit ",(0,s.jsx)(n.code,{children:"help"})," command, add ",(0,s.jsx)(n.code,{children:"@oclif/plugin-help"})," as an ",(0,s.jsx)(n.a,{href:"/docs/plugins",children:"oclif plugin in your config"}),"."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"$ my-cli help\n"})}),"\n",(0,s.jsx)(n.h2,{id:"custom-help",children:"Custom Help"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"$ yarn add @oclif/core --latest\n"})}),"\n",(0,s.jsx)(n.p,{children:"To get started, first define the filepath to your help class in oclif's config in package.json. This is a relative path to the help class, without a file extension."}),"\n",(0,s.jsx)(n.p,{children:'For this example, the help class will be created in a file at "[project root]/src/help.ts".'}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:'{\n // ...\n "oclif": {\n "helpClass": "./dist/help"\n // ...\n }\n // ...\n}\n'})}),"\n",(0,s.jsxs)(n.p,{children:["From here there are two paths, implement the ",(0,s.jsx)(n.code,{children:"HelpBase"})," abstract class yourself or overwrite the parts of the default ",(0,s.jsx)(n.code,{children:"Help"})," class you want to customize (ex: how command usage is displayed). We recommend the latter approach but cover both below."]}),"\n",(0,s.jsxs)(n.h2,{id:"extending-the-helpbase-class",children:["Extending the ",(0,s.jsx)(n.code,{children:"HelpBase"})," class"]}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"HelpBase"})," abstract class provides a starting point requiring the minimum needed methods implemented to be compatible with oclif."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-TypeScript",children:"import {Command, HelpBase} from '@oclif/core';\n\nexport default class CustomHelp extends HelpBase {\n showHelp(args: string[]) {\n console.log('This will be displayed in multi-command CLIs')\n }\n\n showCommandHelp(command: Command) {\n console.log('This will be displayed in single-command CLIs')\n }\n}\n"})}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"showHelp"})," method is called by oclif to display help in multi-command CLIs, while ",(0,s.jsx)(n.code,{children:"showCommandHelp"})," is called directly for single-command CLIs."]}),"\n",(0,s.jsxs)(n.p,{children:["The class is instantiated with a ",(0,s.jsx)(n.code,{children:"config"})," property that provides helpful context for constructing your custom output."]}),"\n",(0,s.jsxs)(n.p,{children:["To see an example of what is possible take a look at the source code for the ",(0,s.jsxs)(n.a,{href:"https://github.com/oclif/core/blob/main/src/help/index.ts",children:["default ",(0,s.jsx)(n.code,{children:"Help"})," class exported from @oclif/core"]}),"."]}),"\n",(0,s.jsxs)(n.h2,{id:"extending-the-default-help-class",children:["Extending the default ",(0,s.jsx)(n.code,{children:"Help"})," class"]}),"\n",(0,s.jsxs)(n.p,{children:["The default ",(0,s.jsx)(n.code,{children:"Help"})," class provides many method \u201chooks\u201d that make it easy to override the particular parts of help's output you want to customize."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-TypeScript",children:"import {Command, Help, Topic} from '@oclif/core';\n\nexport default class MyHelpClass extends Help {\n // acts as a \"router\"\n // and based on the args it receives\n // calls one of showRootHelp, showTopicHelp,\n // or showCommandHelp\n showHelp(args: string[]): void {\n }\n\n // display the root help of a CLI\n showRootHelp(): void {\n }\n\n // display help for a topic\n showTopicHelp(topic: Topic): void {\n }\n\n // display help for a command\n showCommandHelp(command: Command): void {\n }\n\n // the default implementations of showRootHelp\n // showTopicHelp and showCommandHelp\n // will call various format methods that\n // provide the formatting for their corresponding\n // help sections;\n // these can be overwritten as well\n\n // the formatting responsible for the header\n // displayed for the root help\n formatRoot(): string {\n }\n\n // the formatting for an individual topic\n formatTopic(topic: Config.Topic): string {\n }\n\n // the formatting for a list of topics\n protected formatTopics(topics: Config.Topic[]): string {\n }\n\n // the formatting for a list of commands\n formatCommands(commands: Config.Command[]): string {\n }\n\n // the formatting for an individual command\n formatCommand(command: Config.Command): string {\n }\n}\n"})}),"\n",(0,s.jsxs)(n.p,{children:["To see the default implementation of these methods take a look at the ",(0,s.jsxs)(n.a,{href:"https://github.com/oclif/core/blob/main/src/help/index.ts",children:["default ",(0,s.jsx)(n.code,{children:"Help"})," class exported from @oclif/core"]}),"."]}),"\n",(0,s.jsxs)(n.p,{children:["To start experimenting, define ",(0,s.jsx)(n.code,{children:"showCommandHelp"})," in your custom help class and change the output."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-TypeScript",children:"import {Command, Help, Topic} from '@oclif/core';\n\nexport default class MyHelpClass extends Help {\n public showCommandHelp(command: Config.Command) {\n console.log('Display my custom command help!')\n }\n}\n"})}),"\n",(0,s.jsx)(n.p,{children:"Then run help for any command."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"$ my-cli login --help\nDisplay my custom command help!\n"})}),"\n",(0,s.jsx)(n.h2,{id:"building-custom-help-classes-in-javascript-projects",children:"Building custom help classes in JavaScript projects"}),"\n",(0,s.jsxs)(n.p,{children:['These examples above followed a TypeScript project. For JavaScript project with an example help file at "[project root]/src/help.js" would have a package.json with the ',(0,s.jsx)(n.code,{children:"helpClass"})," defined:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:'{\n // ...\n "oclif": {\n "helpClass": "./src/help"\n // ...\n }\n // ...\n}\n'})}),"\n",(0,s.jsx)(n.p,{children:"The imports are handled slightly different for JavaScript projects but the rest of the help class mimic the TypeScript examples above, except without type annotations."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-js",children:"const {HelpBase} = require('@oclif/core');\n\nmodule.exports = class MyHelpClass extends HelpBase {\n showHelp(args) {\n console.log('This will be displayed in multi-command CLIs')\n }\n\n showCommandHelp(command) {\n console.log('This will be displayed for a single command')\n }\n}\n"})}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-js",children:"const {Help} = require('@oclif/core');\n\nmodule.exports = class MyHelpClass extends Help {\n showHelp(args) {\n }\n\n showRootHelp() {\n }\n\n showTopicHelp(topic) {\n }\n\n showCommandHelp(command) {\n }\n\n formatRoot() {\n }\n\n formatTopic(topic) {\n }\n\n formatTopics(topics) {\n }\n\n formatCommands(commands) {\n }\n\n formatCommand(command) {\n }\n}\n"})})]})}function p(e={}){const{wrapper:n}={...(0,l.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,o)=>{o.d(n,{R:()=>i,x:()=>c});var s=o(6540);const l={},t=s.createContext(l);function i(e){const n=s.useContext(t);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(l):e.components||l:i(e.components),s.createElement(t.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
+"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[9036],{354:(e,n,o)=>{o.r(n),o.d(n,{assets:()=>a,contentTitle:()=>i,default:()=>p,frontMatter:()=>t,metadata:()=>c,toc:()=>r});var s=o(4848),l=o(8453);const t={title:"Help Classes"},i=void 0,c={id:"help_classes",title:"Help Classes",description:"Out of the box oclif provides a great help experience for CLIs. Users can invoke help with the --help flag.",source:"@site/../docs/help_classes.md",sourceDirName:".",slug:"/help_classes",permalink:"/docs/help_classes",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/help_classes.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711137687,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Help Classes"},sidebar:"docs",previous:{title:"Plugins",permalink:"/docs/plugins"},next:{title:"Error Handling",permalink:"/docs/error_handling"}},a={},r=[{value:"Custom Help",id:"custom-help",level:2},{value:"Extending the HelpBase class",id:"extending-the-helpbase-class",level:2},{value:"Extending the default Help class",id:"extending-the-default-help-class",level:2},{value:"Building custom help classes in JavaScript projects",id:"building-custom-help-classes-in-javascript-projects",level:2}];function d(e){const n={a:"a",code:"code",h2:"h2",p:"p",pre:"pre",...(0,l.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsxs)(n.p,{children:["Out of the box oclif provides a great help experience for CLIs. Users can invoke help with the ",(0,s.jsx)(n.code,{children:"--help"})," flag."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"$ my-cli login --help\n"})}),"\n",(0,s.jsxs)(n.p,{children:["If you want your CLI to have an explicit ",(0,s.jsx)(n.code,{children:"help"})," command, add ",(0,s.jsx)(n.code,{children:"@oclif/plugin-help"})," as an ",(0,s.jsx)(n.a,{href:"/docs/plugins",children:"oclif plugin in your config"}),"."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"$ my-cli help\n"})}),"\n",(0,s.jsx)(n.h2,{id:"custom-help",children:"Custom Help"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"$ yarn add @oclif/core --latest\n"})}),"\n",(0,s.jsx)(n.p,{children:"To get started, first define the filepath to your help class in oclif's config in package.json. This is a relative path to the help class, without a file extension."}),"\n",(0,s.jsx)(n.p,{children:'For this example, the help class will be created in a file at "[project root]/src/help.ts".'}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:'{\n // ...\n "oclif": {\n "helpClass": "./dist/help"\n // ...\n }\n // ...\n}\n'})}),"\n",(0,s.jsxs)(n.p,{children:["From here there are two paths, implement the ",(0,s.jsx)(n.code,{children:"HelpBase"})," abstract class yourself or overwrite the parts of the default ",(0,s.jsx)(n.code,{children:"Help"})," class you want to customize (ex: how command usage is displayed). We recommend the latter approach but cover both below."]}),"\n",(0,s.jsxs)(n.h2,{id:"extending-the-helpbase-class",children:["Extending the ",(0,s.jsx)(n.code,{children:"HelpBase"})," class"]}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"HelpBase"})," abstract class provides a starting point requiring the minimum needed methods implemented to be compatible with oclif."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-TypeScript",children:"import {Command, HelpBase} from '@oclif/core';\n\nexport default class CustomHelp extends HelpBase {\n showHelp(args: string[]) {\n console.log('This will be displayed in multi-command CLIs')\n }\n\n showCommandHelp(command: Command) {\n console.log('This will be displayed in single-command CLIs')\n }\n}\n"})}),"\n",(0,s.jsxs)(n.p,{children:["The ",(0,s.jsx)(n.code,{children:"showHelp"})," method is called by oclif to display help in multi-command CLIs, while ",(0,s.jsx)(n.code,{children:"showCommandHelp"})," is called directly for single-command CLIs."]}),"\n",(0,s.jsxs)(n.p,{children:["The class is instantiated with a ",(0,s.jsx)(n.code,{children:"config"})," property that provides helpful context for constructing your custom output."]}),"\n",(0,s.jsxs)(n.p,{children:["To see an example of what is possible take a look at the source code for the ",(0,s.jsxs)(n.a,{href:"https://github.com/oclif/core/blob/main/src/help/index.ts",children:["default ",(0,s.jsx)(n.code,{children:"Help"})," class exported from @oclif/core"]}),"."]}),"\n",(0,s.jsxs)(n.h2,{id:"extending-the-default-help-class",children:["Extending the default ",(0,s.jsx)(n.code,{children:"Help"})," class"]}),"\n",(0,s.jsxs)(n.p,{children:["The default ",(0,s.jsx)(n.code,{children:"Help"})," class provides many method \u201chooks\u201d that make it easy to override the particular parts of help's output you want to customize."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-TypeScript",children:"import {Command, Help, Topic} from '@oclif/core';\n\nexport default class MyHelpClass extends Help {\n // acts as a \"router\"\n // and based on the args it receives\n // calls one of showRootHelp, showTopicHelp,\n // or showCommandHelp\n showHelp(args: string[]): void {\n }\n\n // display the root help of a CLI\n showRootHelp(): void {\n }\n\n // display help for a topic\n showTopicHelp(topic: Topic): void {\n }\n\n // display help for a command\n showCommandHelp(command: Command): void {\n }\n\n // the default implementations of showRootHelp\n // showTopicHelp and showCommandHelp\n // will call various format methods that\n // provide the formatting for their corresponding\n // help sections;\n // these can be overwritten as well\n\n // the formatting responsible for the header\n // displayed for the root help\n formatRoot(): string {\n }\n\n // the formatting for an individual topic\n formatTopic(topic: Config.Topic): string {\n }\n\n // the formatting for a list of topics\n protected formatTopics(topics: Config.Topic[]): string {\n }\n\n // the formatting for a list of commands\n formatCommands(commands: Config.Command[]): string {\n }\n\n // the formatting for an individual command\n formatCommand(command: Config.Command): string {\n }\n}\n"})}),"\n",(0,s.jsxs)(n.p,{children:["To see the default implementation of these methods take a look at the ",(0,s.jsxs)(n.a,{href:"https://github.com/oclif/core/blob/main/src/help/index.ts",children:["default ",(0,s.jsx)(n.code,{children:"Help"})," class exported from @oclif/core"]}),"."]}),"\n",(0,s.jsxs)(n.p,{children:["To start experimenting, define ",(0,s.jsx)(n.code,{children:"showCommandHelp"})," in your custom help class and change the output."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-TypeScript",children:"import {Command, Help, Topic} from '@oclif/core';\n\nexport default class MyHelpClass extends Help {\n public showCommandHelp(command: Config.Command) {\n console.log('Display my custom command help!')\n }\n}\n"})}),"\n",(0,s.jsx)(n.p,{children:"Then run help for any command."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:"$ my-cli login --help\nDisplay my custom command help!\n"})}),"\n",(0,s.jsx)(n.h2,{id:"building-custom-help-classes-in-javascript-projects",children:"Building custom help classes in JavaScript projects"}),"\n",(0,s.jsxs)(n.p,{children:['These examples above followed a TypeScript project. For JavaScript project with an example help file at "[project root]/src/help.js" would have a package.json with the ',(0,s.jsx)(n.code,{children:"helpClass"})," defined:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{children:'{\n // ...\n "oclif": {\n "helpClass": "./src/help"\n // ...\n }\n // ...\n}\n'})}),"\n",(0,s.jsx)(n.p,{children:"The imports are handled slightly different for JavaScript projects but the rest of the help class mimic the TypeScript examples above, except without type annotations."}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-js",children:"const {HelpBase} = require('@oclif/core');\n\nmodule.exports = class MyHelpClass extends HelpBase {\n showHelp(args) {\n console.log('This will be displayed in multi-command CLIs')\n }\n\n showCommandHelp(command) {\n console.log('This will be displayed for a single command')\n }\n}\n"})}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-js",children:"const {Help} = require('@oclif/core');\n\nmodule.exports = class MyHelpClass extends Help {\n showHelp(args) {\n }\n\n showRootHelp() {\n }\n\n showTopicHelp(topic) {\n }\n\n showCommandHelp(command) {\n }\n\n formatRoot() {\n }\n\n formatTopic(topic) {\n }\n\n formatTopics(topics) {\n }\n\n formatCommands(commands) {\n }\n\n formatCommand(command) {\n }\n}\n"})})]})}function p(e={}){const{wrapper:n}={...(0,l.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},8453:(e,n,o)=>{o.d(n,{R:()=>i,x:()=>c});var s=o(6540);const l={},t=s.createContext(l);function i(e){const n=s.useContext(t);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(l):e.components||l:i(e.components),s.createElement(t.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/f182954c.67c31c13.js b/assets/js/f182954c.a5c6b274.js
similarity index 96%
rename from assets/js/f182954c.67c31c13.js
rename to assets/js/f182954c.a5c6b274.js
index 6e74b5db..3344c542 100644
--- a/assets/js/f182954c.67c31c13.js
+++ b/assets/js/f182954c.a5c6b274.js
@@ -1 +1 @@
-"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[607],{3685:(e,t,o)=>{o.r(t),o.d(t,{assets:()=>c,contentTitle:()=>i,default:()=>u,frontMatter:()=>n,metadata:()=>l,toc:()=>a});var r=o(4848),s=o(8453);const n={title:"Related Repositories"},i=void 0,l={id:"related_repos",title:"Related Repositories",description:"* @oclif/core - Base library for oclif CLIs or plugins. This can be used directly without the generator.",source:"@site/../docs/related_repos.md",sourceDirName:".",slug:"/related_repos",permalink:"/docs/related_repos",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/related_repos.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711121897,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Related Repositories"},sidebar:"docs",previous:{title:"External Links",permalink:"/docs/external_links"},next:{title:"How We Work",permalink:"/docs/how_we_work"}},c={},a=[];function d(e){const t={a:"a",li:"li",ul:"ul",...(0,s.R)(),...e.components};return(0,r.jsxs)(t.ul,{children:["\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.a,{href:"https://github.com/oclif/core",children:"@oclif/core"})," - Base library for oclif CLIs or plugins. This can be used directly without the generator."]}),"\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.a,{href:"https://github.com/oclif/test",children:"@oclif/test"})," - Test helper for oclif."]}),"\n"]})}function u(e={}){const{wrapper:t}={...(0,s.R)(),...e.components};return t?(0,r.jsx)(t,{...e,children:(0,r.jsx)(d,{...e})}):d(e)}},8453:(e,t,o)=>{o.d(t,{R:()=>i,x:()=>l});var r=o(6540);const s={},n=r.createContext(s);function i(e){const t=r.useContext(n);return r.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function l(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:i(e.components),r.createElement(n.Provider,{value:t},e.children)}}}]);
\ No newline at end of file
+"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[607],{3685:(e,t,o)=>{o.r(t),o.d(t,{assets:()=>c,contentTitle:()=>i,default:()=>u,frontMatter:()=>n,metadata:()=>l,toc:()=>a});var r=o(4848),s=o(8453);const n={title:"Related Repositories"},i=void 0,l={id:"related_repos",title:"Related Repositories",description:"* @oclif/core - Base library for oclif CLIs or plugins. This can be used directly without the generator.",source:"@site/../docs/related_repos.md",sourceDirName:".",slug:"/related_repos",permalink:"/docs/related_repos",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/related_repos.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711137687,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Related Repositories"},sidebar:"docs",previous:{title:"External Links",permalink:"/docs/external_links"},next:{title:"How We Work",permalink:"/docs/how_we_work"}},c={},a=[];function d(e){const t={a:"a",li:"li",ul:"ul",...(0,s.R)(),...e.components};return(0,r.jsxs)(t.ul,{children:["\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.a,{href:"https://github.com/oclif/core",children:"@oclif/core"})," - Base library for oclif CLIs or plugins. This can be used directly without the generator."]}),"\n",(0,r.jsxs)(t.li,{children:[(0,r.jsx)(t.a,{href:"https://github.com/oclif/test",children:"@oclif/test"})," - Test helper for oclif."]}),"\n"]})}function u(e={}){const{wrapper:t}={...(0,s.R)(),...e.components};return t?(0,r.jsx)(t,{...e,children:(0,r.jsx)(d,{...e})}):d(e)}},8453:(e,t,o)=>{o.d(t,{R:()=>i,x:()=>l});var r=o(6540);const s={},n=r.createContext(s);function i(e){const t=r.useContext(n);return r.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function l(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:i(e.components),r.createElement(n.Provider,{value:t},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/f6c5328e.a958af26.js b/assets/js/f6c5328e.f3572610.js
similarity index 98%
rename from assets/js/f6c5328e.a958af26.js
rename to assets/js/f6c5328e.f3572610.js
index 7794bd10..1ea2245d 100644
--- a/assets/js/f6c5328e.a958af26.js
+++ b/assets/js/f6c5328e.f3572610.js
@@ -1 +1 @@
-"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[9181],{5500:(e,n,o)=>{o.r(n),o.d(n,{assets:()=>a,contentTitle:()=>c,default:()=>h,frontMatter:()=>i,metadata:()=>l,toc:()=>r});var t=o(4848),s=o(8453);const i={title:"Hooks"},c=void 0,l={id:"hooks",title:"Hooks",description:"oclif exposes lifecycle event hooks such as init and commandnotfound. See below for a list of all the lifecycle events. In addition to these built-in events, you can create your own events and allow commands/plugins to watch for these custom events. It's a great way to allow multiple plugins to interact with each other.",source:"@site/../docs/hooks.md",sourceDirName:".",slug:"/hooks",permalink:"/docs/hooks",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/hooks.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711121897,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Hooks"},sidebar:"docs",previous:{title:"Topic Separators",permalink:"/docs/topic_separator"},next:{title:"Plugins",permalink:"/docs/plugins"}},a={},r=[{value:"Lifecycle Events",id:"lifecycle-events",level:2},{value:"Custom Events",id:"custom-events",level:2}];function d(e){const n={a:"a",code:"code",h2:"h2",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,s.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsxs)(n.p,{children:["oclif exposes lifecycle event hooks such as ",(0,t.jsx)(n.code,{children:"init"})," and ",(0,t.jsx)(n.code,{children:"command_not_found"}),". ",(0,t.jsx)(n.a,{href:"#lifecycle-events",children:"See below for a list of all the lifecycle events"}),". In addition to these built-in events, you can create your own events and allow commands/plugins to watch for these custom events. It's a great way to allow multiple plugins to interact with each other."]}),"\n",(0,t.jsxs)(n.p,{children:["Multiple hooks are run in parallel. ",(0,t.jsx)(n.strong,{children:"This behavior may change in a future release."})]}),"\n",(0,t.jsx)(n.p,{children:"A basic hook looks like the following in TypeScript:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"import {Hook} from '@oclif/core'\n\nconst hook: Hook<'init'> = async function (options) {\n console.log(`example init hook running before ${options.id}`)\n}\n\nexport default hook\n"})}),"\n",(0,t.jsxs)(n.p,{children:["The hook must also be declared with the event's name and hook's file path under oclif's settings in ",(0,t.jsx)(n.code,{children:"package.json"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-js",children:' "oclif": {\n "commands": "./lib/commands",\n "hooks": {\n "init": "./lib/hooks/init/example"\n }\n }\n'})}),"\n",(0,t.jsx)(n.p,{children:"Multiple hooks of the same event type can be declared with an array."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-js",children:' "oclif": {\n "commands": "./lib/commands",\n "hooks": {\n "init": [\n "./lib/hooks/init/example",\n "./lib/hooks/init/another_hook"\n ]\n }\n }\n'})}),"\n",(0,t.jsxs)(n.p,{children:["You can create hooks with ",(0,t.jsx)(n.code,{children:"oclif generate hook myhook --event=init"}),"."]}),"\n",(0,t.jsx)(n.h2,{id:"lifecycle-events",children:"Lifecycle Events"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"init"})," - runs when the CLI is initialized before a command is found to run"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"prerun"})," - runs after ",(0,t.jsx)(n.code,{children:"init"})," and after the command is found, but just before running the command itself"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"postrun"})," - runs after the command only if the command finishes with no error"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"command_not_found"})," - runs if a command is not found before the error is displayed"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"custom-events",children:"Custom Events"}),"\n",(0,t.jsxs)(n.p,{children:["Custom events are just like lifecycle events, but you need to call ",(0,t.jsx)(n.code,{children:"this.config.runHook()"})," to fire the event."]}),"\n",(0,t.jsx)(n.p,{children:"For example, you could define an analytics post function that you will run in your command after submitting analytics telemetry. First define:"}),"\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"src/hooks/analytics/post.ts"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"const hook = async function (options: {id: string}) {\n // code to post options.id to analytics server\n}\n\nexport default hook\n"})}),"\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"package.json"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-js",children:' "oclif": {\n "commands": "./lib/commands",\n "hooks": {\n "analytics": "./lib/hooks/analytics/post"\n },\n },\n'})}),"\n",(0,t.jsx)(n.p,{children:"Then in any command you want to trigger the event:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-js",children:"export class extends Command {\n async run() {\n // emit analytics\n await this.config.runHook('analytics', {id: 'my_command'})\n }\n}\n"})}),"\n",(0,t.jsxs)(n.p,{children:["If you need to exit during a hook, use ",(0,t.jsx)(n.code,{children:"this.error()"})," or ",(0,t.jsx)(n.code,{children:"this.exit()"}),". Otherwise the hook will just emit a warning. This is to prevent an issue such as a plugin failing in ",(0,t.jsx)(n.code,{children:"init"})," causing the entire CLI to not function."]})]})}function h(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},8453:(e,n,o)=>{o.d(n,{R:()=>c,x:()=>l});var t=o(6540);const s={},i=t.createContext(s);function c(e){const n=t.useContext(i);return t.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:c(e.components),t.createElement(i.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
+"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[9181],{5500:(e,n,o)=>{o.r(n),o.d(n,{assets:()=>a,contentTitle:()=>c,default:()=>h,frontMatter:()=>i,metadata:()=>l,toc:()=>r});var t=o(4848),s=o(8453);const i={title:"Hooks"},c=void 0,l={id:"hooks",title:"Hooks",description:"oclif exposes lifecycle event hooks such as init and commandnotfound. See below for a list of all the lifecycle events. In addition to these built-in events, you can create your own events and allow commands/plugins to watch for these custom events. It's a great way to allow multiple plugins to interact with each other.",source:"@site/../docs/hooks.md",sourceDirName:".",slug:"/hooks",permalink:"/docs/hooks",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/hooks.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711137687,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Hooks"},sidebar:"docs",previous:{title:"Topic Separators",permalink:"/docs/topic_separator"},next:{title:"Plugins",permalink:"/docs/plugins"}},a={},r=[{value:"Lifecycle Events",id:"lifecycle-events",level:2},{value:"Custom Events",id:"custom-events",level:2}];function d(e){const n={a:"a",code:"code",h2:"h2",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,s.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsxs)(n.p,{children:["oclif exposes lifecycle event hooks such as ",(0,t.jsx)(n.code,{children:"init"})," and ",(0,t.jsx)(n.code,{children:"command_not_found"}),". ",(0,t.jsx)(n.a,{href:"#lifecycle-events",children:"See below for a list of all the lifecycle events"}),". In addition to these built-in events, you can create your own events and allow commands/plugins to watch for these custom events. It's a great way to allow multiple plugins to interact with each other."]}),"\n",(0,t.jsxs)(n.p,{children:["Multiple hooks are run in parallel. ",(0,t.jsx)(n.strong,{children:"This behavior may change in a future release."})]}),"\n",(0,t.jsx)(n.p,{children:"A basic hook looks like the following in TypeScript:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"import {Hook} from '@oclif/core'\n\nconst hook: Hook<'init'> = async function (options) {\n console.log(`example init hook running before ${options.id}`)\n}\n\nexport default hook\n"})}),"\n",(0,t.jsxs)(n.p,{children:["The hook must also be declared with the event's name and hook's file path under oclif's settings in ",(0,t.jsx)(n.code,{children:"package.json"}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-js",children:' "oclif": {\n "commands": "./lib/commands",\n "hooks": {\n "init": "./lib/hooks/init/example"\n }\n }\n'})}),"\n",(0,t.jsx)(n.p,{children:"Multiple hooks of the same event type can be declared with an array."}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-js",children:' "oclif": {\n "commands": "./lib/commands",\n "hooks": {\n "init": [\n "./lib/hooks/init/example",\n "./lib/hooks/init/another_hook"\n ]\n }\n }\n'})}),"\n",(0,t.jsxs)(n.p,{children:["You can create hooks with ",(0,t.jsx)(n.code,{children:"oclif generate hook myhook --event=init"}),"."]}),"\n",(0,t.jsx)(n.h2,{id:"lifecycle-events",children:"Lifecycle Events"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"init"})," - runs when the CLI is initialized before a command is found to run"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"prerun"})," - runs after ",(0,t.jsx)(n.code,{children:"init"})," and after the command is found, but just before running the command itself"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"postrun"})," - runs after the command only if the command finishes with no error"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"command_not_found"})," - runs if a command is not found before the error is displayed"]}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"custom-events",children:"Custom Events"}),"\n",(0,t.jsxs)(n.p,{children:["Custom events are just like lifecycle events, but you need to call ",(0,t.jsx)(n.code,{children:"this.config.runHook()"})," to fire the event."]}),"\n",(0,t.jsx)(n.p,{children:"For example, you could define an analytics post function that you will run in your command after submitting analytics telemetry. First define:"}),"\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"src/hooks/analytics/post.ts"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-typescript",children:"const hook = async function (options: {id: string}) {\n // code to post options.id to analytics server\n}\n\nexport default hook\n"})}),"\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.strong,{children:"package.json"})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-js",children:' "oclif": {\n "commands": "./lib/commands",\n "hooks": {\n "analytics": "./lib/hooks/analytics/post"\n },\n },\n'})}),"\n",(0,t.jsx)(n.p,{children:"Then in any command you want to trigger the event:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-js",children:"export class extends Command {\n async run() {\n // emit analytics\n await this.config.runHook('analytics', {id: 'my_command'})\n }\n}\n"})}),"\n",(0,t.jsxs)(n.p,{children:["If you need to exit during a hook, use ",(0,t.jsx)(n.code,{children:"this.error()"})," or ",(0,t.jsx)(n.code,{children:"this.exit()"}),". Otherwise the hook will just emit a warning. This is to prevent an issue such as a plugin failing in ",(0,t.jsx)(n.code,{children:"init"})," causing the entire CLI to not function."]})]})}function h(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},8453:(e,n,o)=>{o.d(n,{R:()=>c,x:()=>l});var t=o(6540);const s={},i=t.createContext(s);function c(e){const n=t.useContext(i);return t.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:c(e.components),t.createElement(i.Provider,{value:n},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/f905d0fe.2c295ea7.js b/assets/js/f905d0fe.457b8b04.js
similarity index 96%
rename from assets/js/f905d0fe.2c295ea7.js
rename to assets/js/f905d0fe.457b8b04.js
index 8c4febd3..5e729cf5 100644
--- a/assets/js/f905d0fe.2c295ea7.js
+++ b/assets/js/f905d0fe.457b8b04.js
@@ -1 +1 @@
-"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[6122],{156:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>r,contentTitle:()=>i,default:()=>u,frontMatter:()=>a,metadata:()=>s,toc:()=>d});var o=n(4848),c=n(8453);const a={title:"Command Execution"},i=void 0,s={id:"command_execution",title:"Command Execution",description:"Below is a diagram that outlines at a high level the process that occurs every time a user executes an oclif command.",source:"@site/../docs/command_execution.md",sourceDirName:".",slug:"/command_execution",permalink:"/docs/command_execution",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/command_execution.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711121897,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Command Execution"},sidebar:"docs",previous:{title:"Generator Commands",permalink:"/docs/generator_commands"},next:{title:"Plugin Loading",permalink:"/docs/plugin_loading"}},r={},d=[];function m(e){const t={img:"img",p:"p",...(0,c.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(t.p,{children:"Below is a diagram that outlines at a high level the process that occurs every time a user executes an oclif command."}),"\n",(0,o.jsx)(t.p,{children:(0,o.jsx)(t.img,{alt:"command execution flow",src:n(28).A+"",width:"3258",height:"4910"})})]})}function u(e={}){const{wrapper:t}={...(0,c.R)(),...e.components};return t?(0,o.jsx)(t,{...e,children:(0,o.jsx)(m,{...e})}):m(e)}},28:(e,t,n)=>{n.d(t,{A:()=>o});const o=n.p+"assets/images/command-execution-flow-7722f834b51111bcf89f6c2f7ae2cdf5.jpg"},8453:(e,t,n)=>{n.d(t,{R:()=>i,x:()=>s});var o=n(6540);const c={},a=o.createContext(c);function i(e){const t=o.useContext(a);return o.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function s(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(c):e.components||c:i(e.components),o.createElement(a.Provider,{value:t},e.children)}}}]);
\ No newline at end of file
+"use strict";(self.webpackChunk=self.webpackChunk||[]).push([[6122],{156:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>r,contentTitle:()=>i,default:()=>u,frontMatter:()=>a,metadata:()=>s,toc:()=>d});var o=n(4848),c=n(8453);const a={title:"Command Execution"},i=void 0,s={id:"command_execution",title:"Command Execution",description:"Below is a diagram that outlines at a high level the process that occurs every time a user executes an oclif command.",source:"@site/../docs/command_execution.md",sourceDirName:".",slug:"/command_execution",permalink:"/docs/command_execution",draft:!1,unlisted:!1,editUrl:"https://github.com/oclif/oclif.github.io/tree/docs/docs/../docs/command_execution.md",tags:[],version:"current",lastUpdatedBy:"Mike Donnalley",lastUpdatedAt:1711137687,formattedLastUpdatedAt:"Mar 22, 2024",frontMatter:{title:"Command Execution"},sidebar:"docs",previous:{title:"Generator Commands",permalink:"/docs/generator_commands"},next:{title:"Plugin Loading",permalink:"/docs/plugin_loading"}},r={},d=[];function m(e){const t={img:"img",p:"p",...(0,c.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(t.p,{children:"Below is a diagram that outlines at a high level the process that occurs every time a user executes an oclif command."}),"\n",(0,o.jsx)(t.p,{children:(0,o.jsx)(t.img,{alt:"command execution flow",src:n(28).A+"",width:"3258",height:"4910"})})]})}function u(e={}){const{wrapper:t}={...(0,c.R)(),...e.components};return t?(0,o.jsx)(t,{...e,children:(0,o.jsx)(m,{...e})}):m(e)}},28:(e,t,n)=>{n.d(t,{A:()=>o});const o=n.p+"assets/images/command-execution-flow-7722f834b51111bcf89f6c2f7ae2cdf5.jpg"},8453:(e,t,n)=>{n.d(t,{R:()=>i,x:()=>s});var o=n(6540);const c={},a=o.createContext(c);function i(e){const t=o.useContext(a);return o.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function s(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(c):e.components||c:i(e.components),o.createElement(a.Provider,{value:t},e.children)}}}]);
\ No newline at end of file
diff --git a/assets/js/main.8b08819f.js b/assets/js/main.8b08819f.js
deleted file mode 100644
index 355e5ff2..00000000
--- a/assets/js/main.8b08819f.js
+++ /dev/null
@@ -1,2 +0,0 @@
-/*! For license information please see main.8b08819f.js.LICENSE.txt */
-(self.webpackChunk=self.webpackChunk||[]).push([[8792],{9188:(e,t,n)=>{"use strict";n.d(t,{W:()=>o});var r=n(6540);function o(){return r.createElement("svg",{width:"20",height:"20",className:"DocSearch-Search-Icon",viewBox:"0 0 20 20","aria-hidden":"true"},r.createElement("path",{d:"M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z",stroke:"currentColor",fill:"none",fillRule:"evenodd",strokeLinecap:"round",strokeLinejoin:"round"}))}},8328:(e,t,n)=>{"use strict";n.d(t,{A:()=>f});n(6540);var r=n(3259),o=n.n(r),a=n(4054);const i={"0085e091":[function(){return n.e(4119).then(n.bind(n,7317))},"@site/blog/2018-03-20-introducing-oclif.md?truncated=true",7317],"03a88bad":[function(){return n.e(8078).then(n.bind(n,2584))},"@site/../docs/index.md",2584],"03abeb31":[function(){return n.e(844).then(n.bind(n,3680))},"@site/../docs/debugging.md",3680],"04855d6d":[function(){return n.e(4059).then(n.bind(n,4836))},"@site/blog/2019-02-20-cli-flags-explained.md",4836],"0b218a01":[function(){return n.e(3454).then(n.bind(n,6040))},"@site/../docs/aliases.md",6040],"104cbb75":[function(){return n.e(6471).then(n.bind(n,8907))},"@site/../docs/flexible_taxonomy.md",8907],"169e66bc":[function(){return n.e(8161).then(n.bind(n,9952))},"@site/blog/2022-01-12-announcing-oclif-v2.md",9952],17896441:[function(){return Promise.all([n.e(1869),n.e(5463),n.e(8401)]).then(n.bind(n,5022))},"@theme/DocItem",5022],"19fd9079":[function(){return n.e(8080).then(n.bind(n,4015))},"@site/../docs/external_links.md",4015],"1a4e3797":[function(){return Promise.all([n.e(1869),n.e(2138)]).then(n.bind(n,673))},"@theme/SearchPage",673],"1d5c88f5":[function(){return n.e(8467).then(n.bind(n,9328))},"@site/blog/2019-02-20-cli-flags-explained.md?truncated=true",9328],"1ed4142b":[function(){return n.e(3782).then(n.bind(n,32))},"@site/../docs/jit_plugins.md",32],"1f61ef73":[function(){return n.e(5082).then(n.bind(n,492))},"@site/../docs/error_handling.md",492],"2486267b":[function(){return n.e(9e3).then(n.bind(n,7413))},"@site/../docs/spinner.md",7413],"253cd3dc":[function(){return n.e(2106).then(n.bind(n,3132))},"@site/blog/2022-01-12-announcing-oclif-v2.md?truncated=true",3132],"258a6413":[function(){return n.e(3651).then(n.bind(n,5453))},"@site/../docs/single_command_cli.md",5453],"28395ba4":[function(){return n.e(1139).then(n.t.bind(n,1966,19))},"/home/runner/work/oclif.github.io/oclif.github.io/website/.docusaurus/docusaurus-plugin-content-docs/default/plugin-route-context-module-100.json",1966],"2a33acc4":[function(){return n.e(1427).then(n.bind(n,2130))},"@site/../docs/topics.md",2130],"2f98ad87":[function(){return n.e(8664).then(n.bind(n,2678))},"@site/../docs/generator_commands.md",2678],"3042343a":[function(){return n.e(7777).then(n.bind(n,2443))},"@site/../docs/flags.md",2443],"30d74566":[function(){return n.e(4260).then(n.bind(n,3602))},"@site/../docs/command_discovery_strategies.md",3602],32060389:[function(){return n.e(7996).then(n.bind(n,1916))},"@site/../docs/table.md",1916],"35586d92":[function(){return n.e(7187).then(n.bind(n,1810))},"@site/../docs/plugin_loading.md",1810],"3ba497c2":[function(){return n.e(6332).then(n.t.bind(n,4061,19))},"/home/runner/work/oclif.github.io/oclif.github.io/website/.docusaurus/docusaurus-plugin-content-pages/default/plugin-route-context-module-100.json",4061],"3bc14f20":[function(){return n.e(172).then(n.t.bind(n,2945,19))},"/home/runner/work/oclif.github.io/oclif.github.io/website/.docusaurus/docusaurus-plugin-content-blog/default/plugin-route-context-module-100.json",2945],"3e452c7e":[function(){return n.e(55).then(n.bind(n,7780))},"@site/../docs/base_class.md",7780],"49140ced":[function(){return n.e(6485).then(n.bind(n,6667))},"@site/blog/2019-10-31-oclif-node-updates.md?truncated=true",6667],"4fdccd00":[function(){return n.e(1035).then(n.bind(n,3155))},"@site/blog/2018-03-20-introducing-oclif.md",3155],"53e18611":[function(){return n.e(1777).then(n.bind(n,1098))},"@site/../docs/introduction.md",1098],"5d5620c4":[function(){return n.e(8990).then(n.bind(n,5219))},"@site/../docs/esm.md",5219],"5e95c892":[function(){return n.e(9647).then(n.bind(n,7121))},"@theme/DocsRoot",7121],"5e9f5e1a":[function(){return Promise.resolve().then(n.bind(n,4784))},"@generated/docusaurus.config",4784],"5f98988e":[function(){return n.e(411).then(n.bind(n,1939))},"@site/blog/2019-12-05-oclif-eslint-migration.md?truncated=true",1939],"6de0e435":[function(){return n.e(285).then(n.bind(n,4502))},"@site/blog/2020-05-05-introducing-custom-help-classes.md",4502],"6f3bb722":[function(){return n.e(2961).then(n.bind(n,8976))},"@site/../docs/commands.md",8976],"713bb917":[function(){return n.e(5483).then(n.bind(n,5678))},"@site/../docs/releasing.md",5678],"765c6b61":[function(){return n.e(4295).then(n.bind(n,6601))},"@site/blog/2019-10-31-oclif-node-updates.md",6601],"7b0e8dfa":[function(){return n.e(7386).then(n.bind(n,7154))},"@site/blog/2020-08-26-summer-update.md?truncated=true",7154],"7bd58895":[function(){return n.e(7071).then(n.bind(n,6362))},"@site/../docs/prompting.md",6362],"814f3328":[function(){return n.e(7472).then(n.t.bind(n,5513,19))},"~blog/default/blog-post-list-prop-default.json",5513],"82247a8b":[function(){return n.e(9409).then(n.bind(n,7840))},"@site/../docs/config.md",7840],"853133bb":[function(){return n.e(8204).then(n.bind(n,9585))},"@site/blog/2019-12-05-oclif-eslint-migration.md",9585],"8705a681":[function(){return n.e(125).then(n.bind(n,1766))},"@site/../docs/running_programmatically.md",1766],"935116ff":[function(){return n.e(8212).then(n.bind(n,1687))},"@site/../docs/faqs.md",1687],"935f2afb":[function(){return n.e(8581).then(n.t.bind(n,5610,19))},"~docs/default/version-current-metadata-prop-751.json",5610],"958c0a42":[function(){return n.e(4157).then(n.bind(n,4602))},"@site/blog/2020-05-05-introducing-custom-help-classes.md?truncated=true",4602],"9e4087bc":[function(){return n.e(2711).then(n.bind(n,9331))},"@theme/BlogArchivePage",9331],"9eaa546a":[function(){return n.e(4711).then(n.bind(n,2449))},"@site/../docs/features.md",2449],a6aa9e1f:[function(){return Promise.all([n.e(1869),n.e(5463),n.e(8544),n.e(7643)]).then(n.bind(n,2667))},"@theme/BlogListPage",2667],a7bd4aaa:[function(){return n.e(7098).then(n.bind(n,4532))},"@theme/DocVersionRoot",4532],a92e169d:[function(){return n.e(5924).then(n.bind(n,1177))},"@site/../docs/global_flags.md",1177],a94703ab:[function(){return Promise.all([n.e(1869),n.e(9048)]).then(n.bind(n,2559))},"@theme/DocRoot",2559],a96ec439:[function(){return n.e(1595).then(n.bind(n,1204))},"@site/../docs/notifications.md",1204],b2b675dd:[function(){return n.e(1991).then(n.t.bind(n,9775,19))},"~blog/default/blog-c06.json",9775],b2f554cd:[function(){return n.e(5894).then(n.t.bind(n,6042,19))},"~blog/default/blog-archive-80c.json",6042],b3cc73c6:[function(){return n.e(2381).then(n.bind(n,6957))},"@site/../docs/how_we_work.md",6957],b439faf3:[function(){return n.e(407).then(n.bind(n,9326))},"@site/blog/2020-08-26-summer-update.md",9326],b4a95747:[function(){return n.e(8908).then(n.bind(n,3424))},"@site/../docs/json.md",3424],bc0981ca:[function(){return n.e(8138).then(n.t.bind(n,7757,19))},"/home/runner/work/oclif.github.io/oclif.github.io/website/.docusaurus/docusaurus-theme-search-algolia/default/plugin-route-context-module-100.json",7757],c4b40215:[function(){return n.e(3868).then(n.bind(n,8964))},"@site/blog/2021-03-01-introducing-oclif-core.md?truncated=true",8964],c4f5d8e4:[function(){return n.e(2634).then(n.bind(n,192))},"@site/src/pages/index.js",192],c5890d18:[function(){return n.e(5069).then(n.bind(n,1588))},"@site/../docs/themes.md",1588],c637b865:[function(){return n.e(1979).then(n.bind(n,41))},"@site/blog/2020-07-01-pretty-printable-errors.md",41],c81fd975:[function(){return n.e(218).then(n.bind(n,4240))},"@site/../docs/testing.md",4240],c94a68c1:[function(){return n.e(9604).then(n.bind(n,2391))},"@site/../docs/args.md",2391],ccc49370:[function(){return Promise.all([n.e(1869),n.e(5463),n.e(8544),n.e(3249)]).then(n.bind(n,4029))},"@theme/BlogPostPage",4029],d0e73d62:[function(){return n.e(7642).then(n.bind(n,6158))},"@site/../docs/nsis-installer_customization.md",6158],d665a578:[function(){return n.e(6337).then(n.bind(n,1973))},"@site/../docs/examples.md",1973],d9b0bdb4:[function(){return n.e(908).then(n.bind(n,7949))},"@site/../docs/feedback.md",7949],df1cd967:[function(){return n.e(2977).then(n.bind(n,5391))},"@site/../docs/topic_separator.md",5391],e2e9d59a:[function(){return n.e(7199).then(n.bind(n,2331))},"@site/blog/2020-07-01-pretty-printable-errors.md?truncated=true",2331],e360e27f:[function(){return n.e(191).then(n.bind(n,8504))},"@site/../docs/plugins.md",8504],e3703649:[function(){return n.e(9036).then(n.bind(n,354))},"@site/../docs/help_classes.md",354],f182954c:[function(){return n.e(607).then(n.bind(n,3685))},"@site/../docs/related_repos.md",3685],f6c5328e:[function(){return n.e(9181).then(n.bind(n,5500))},"@site/../docs/hooks.md",5500],f85046f2:[function(){return n.e(3056).then(n.bind(n,5624))},"@site/blog/2021-03-01-introducing-oclif-core.md",5624],f905d0fe:[function(){return n.e(6122).then(n.bind(n,156))},"@site/../docs/command_execution.md",156]};var l=n(4848);function s(e){var t=e.error,n=e.retry,r=e.pastDelay;return t?(0,l.jsxs)("div",{style:{textAlign:"center",color:"#fff",backgroundColor:"#fa383e",borderColor:"#fa383e",borderStyle:"solid",borderRadius:"0.25rem",borderWidth:"1px",boxSizing:"border-box",display:"block",padding:"1rem",flex:"0 0 50%",marginLeft:"25%",marginRight:"25%",marginTop:"5rem",maxWidth:"50%",width:"100%"},children:[(0,l.jsx)("p",{children:String(t)}),(0,l.jsx)("div",{children:(0,l.jsx)("button",{type:"button",onClick:n,children:"Retry"})})]}):r?(0,l.jsx)("div",{style:{display:"flex",justifyContent:"center",alignItems:"center",height:"100vh"},children:(0,l.jsx)("svg",{id:"loader",style:{width:128,height:110,position:"absolute",top:"calc(100vh - 64%)"},viewBox:"0 0 45 45",xmlns:"http://www.w3.org/2000/svg",stroke:"#61dafb",children:(0,l.jsxs)("g",{fill:"none",fillRule:"evenodd",transform:"translate(1 1)",strokeWidth:"2",children:[(0,l.jsxs)("circle",{cx:"22",cy:"22",r:"6",strokeOpacity:"0",children:[(0,l.jsx)("animate",{attributeName:"r",begin:"1.5s",dur:"3s",values:"6;22",calcMode:"linear",repeatCount:"indefinite"}),(0,l.jsx)("animate",{attributeName:"stroke-opacity",begin:"1.5s",dur:"3s",values:"1;0",calcMode:"linear",repeatCount:"indefinite"}),(0,l.jsx)("animate",{attributeName:"stroke-width",begin:"1.5s",dur:"3s",values:"2;0",calcMode:"linear",repeatCount:"indefinite"})]}),(0,l.jsxs)("circle",{cx:"22",cy:"22",r:"6",strokeOpacity:"0",children:[(0,l.jsx)("animate",{attributeName:"r",begin:"3s",dur:"3s",values:"6;22",calcMode:"linear",repeatCount:"indefinite"}),(0,l.jsx)("animate",{attributeName:"stroke-opacity",begin:"3s",dur:"3s",values:"1;0",calcMode:"linear",repeatCount:"indefinite"}),(0,l.jsx)("animate",{attributeName:"stroke-width",begin:"3s",dur:"3s",values:"2;0",calcMode:"linear",repeatCount:"indefinite"})]}),(0,l.jsx)("circle",{cx:"22",cy:"22",r:"8",children:(0,l.jsx)("animate",{attributeName:"r",begin:"0s",dur:"1.5s",values:"6;1;2;3;4;5;6",calcMode:"linear",repeatCount:"indefinite"})})]})})}):null}var u=n(6921),c=n(3102);function d(e,t){if("*"===e)return o()({loading:s,loader:function(){return n.e(2237).then(n.bind(n,2237))},modules:["@theme/NotFound"],webpack:function(){return[2237]},render:function(e,t){var n=e.default;return(0,l.jsx)(c.W,{value:{plugin:{name:"native",id:"default"}},children:(0,l.jsx)(n,Object.assign({},t))})}});var r=a[e+"-"+t],d={},f=[],p=[],m=(0,u.A)(r);return Object.entries(m).forEach((function(e){var t=e[0],n=e[1],r=i[n];r&&(d[t]=r[0],f.push(r[1]),p.push(r[2]))})),o().Map({loading:s,loader:d,modules:f,webpack:function(){return p},render:function(t,n){var o=JSON.parse(JSON.stringify(r));Object.entries(t).forEach((function(t){var n=t[0],r=t[1],a=r.default;if(!a)throw new Error("The page component at "+e+" doesn't have a default export. This makes it impossible to render anything. Consider default-exporting a React component.");"object"!=typeof a&&"function"!=typeof a||Object.keys(r).filter((function(e){return"default"!==e})).forEach((function(e){a[e]=r[e]}));var i=o,l=n.split(".");l.slice(0,-1).forEach((function(e){i=i[e]})),i[l[l.length-1]]=a}));var a=o.__comp;delete o.__comp;var i=o.__context;return delete o.__context,(0,l.jsx)(c.W,{value:i,children:(0,l.jsx)(a,Object.assign({},o,n))})}})}const f=[{path:"/blog",component:d("/blog","37d"),exact:!0},{path:"/blog/2018/03/20/introducing-oclif",component:d("/blog/2018/03/20/introducing-oclif","8a9"),exact:!0},{path:"/blog/2019/02/20/cli-flags-explained",component:d("/blog/2019/02/20/cli-flags-explained","881"),exact:!0},{path:"/blog/2019/10/31/oclif-node-updates",component:d("/blog/2019/10/31/oclif-node-updates","1a7"),exact:!0},{path:"/blog/2019/12/05/oclif-eslint-migration",component:d("/blog/2019/12/05/oclif-eslint-migration","a8a"),exact:!0},{path:"/blog/2020/05/05/introducing-custom-help-classes",component:d("/blog/2020/05/05/introducing-custom-help-classes","3ac"),exact:!0},{path:"/blog/2020/07/01/pretty-printable-errors",component:d("/blog/2020/07/01/pretty-printable-errors","6e9"),exact:!0},{path:"/blog/2020/08/26/summer-update",component:d("/blog/2020/08/26/summer-update","0a9"),exact:!0},{path:"/blog/2021/03/01/introducing-oclif-core",component:d("/blog/2021/03/01/introducing-oclif-core","2e9"),exact:!0},{path:"/blog/2022/01/12/announcing-oclif-v2",component:d("/blog/2022/01/12/announcing-oclif-v2","548"),exact:!0},{path:"/blog/archive",component:d("/blog/archive","ced"),exact:!0},{path:"/search",component:d("/search","ffa"),exact:!0},{path:"/docs",component:d("/docs","149"),routes:[{path:"/docs",component:d("/docs","123"),routes:[{path:"/docs",component:d("/docs","541"),routes:[{path:"/docs/",component:d("/docs/","a6b"),exact:!0},{path:"/docs/aliases",component:d("/docs/aliases","0d8"),exact:!0,sidebar:"docs"},{path:"/docs/args",component:d("/docs/args","9fb"),exact:!0,sidebar:"docs"},{path:"/docs/base_class",component:d("/docs/base_class","c57"),exact:!0,sidebar:"docs"},{path:"/docs/command_discovery_strategies",component:d("/docs/command_discovery_strategies","811"),exact:!0,sidebar:"docs"},{path:"/docs/command_execution",component:d("/docs/command_execution","510"),exact:!0,sidebar:"docs"},{path:"/docs/commands",component:d("/docs/commands","96a"),exact:!0,sidebar:"docs"},{path:"/docs/config",component:d("/docs/config","dd2"),exact:!0,sidebar:"docs"},{path:"/docs/debugging",component:d("/docs/debugging","427"),exact:!0,sidebar:"docs"},{path:"/docs/error_handling",component:d("/docs/error_handling","fd2"),exact:!0,sidebar:"docs"},{path:"/docs/esm",component:d("/docs/esm","903"),exact:!0,sidebar:"docs"},{path:"/docs/examples",component:d("/docs/examples","321"),exact:!0,sidebar:"docs"},{path:"/docs/external_links",component:d("/docs/external_links","bb2"),exact:!0,sidebar:"docs"},{path:"/docs/faqs",component:d("/docs/faqs","ef2"),exact:!0,sidebar:"docs"},{path:"/docs/features",component:d("/docs/features","228"),exact:!0,sidebar:"docs"},{path:"/docs/feedback",component:d("/docs/feedback","0a2"),exact:!0,sidebar:"docs"},{path:"/docs/flags",component:d("/docs/flags","c96"),exact:!0,sidebar:"docs"},{path:"/docs/flexible_taxonomy",component:d("/docs/flexible_taxonomy","2bc"),exact:!0,sidebar:"docs"},{path:"/docs/generator_commands",component:d("/docs/generator_commands","bd4"),exact:!0,sidebar:"docs"},{path:"/docs/global_flags",component:d("/docs/global_flags","52c"),exact:!0,sidebar:"docs"},{path:"/docs/help_classes",component:d("/docs/help_classes","5f9"),exact:!0,sidebar:"docs"},{path:"/docs/hooks",component:d("/docs/hooks","68c"),exact:!0,sidebar:"docs"},{path:"/docs/how_we_work",component:d("/docs/how_we_work","368"),exact:!0,sidebar:"docs"},{path:"/docs/introduction",component:d("/docs/introduction","922"),exact:!0,sidebar:"docs"},{path:"/docs/jit_plugins",component:d("/docs/jit_plugins","d1e"),exact:!0,sidebar:"docs"},{path:"/docs/json",component:d("/docs/json","b5e"),exact:!0,sidebar:"docs"},{path:"/docs/notifications",component:d("/docs/notifications","9aa"),exact:!0,sidebar:"docs"},{path:"/docs/nsis-installer_customization",component:d("/docs/nsis-installer_customization","bcb"),exact:!0,sidebar:"docs"},{path:"/docs/plugin_loading",component:d("/docs/plugin_loading","750"),exact:!0,sidebar:"docs"},{path:"/docs/plugins",component:d("/docs/plugins","fc6"),exact:!0,sidebar:"docs"},{path:"/docs/prompting",component:d("/docs/prompting","721"),exact:!0,sidebar:"docs"},{path:"/docs/related_repos",component:d("/docs/related_repos","435"),exact:!0,sidebar:"docs"},{path:"/docs/releasing",component:d("/docs/releasing","5b4"),exact:!0,sidebar:"docs"},{path:"/docs/running_programmatically",component:d("/docs/running_programmatically","ef2"),exact:!0,sidebar:"docs"},{path:"/docs/single_command_cli",component:d("/docs/single_command_cli","28e"),exact:!0,sidebar:"docs"},{path:"/docs/spinner",component:d("/docs/spinner","947"),exact:!0,sidebar:"docs"},{path:"/docs/table",component:d("/docs/table","c2b"),exact:!0,sidebar:"docs"},{path:"/docs/testing",component:d("/docs/testing","8d8"),exact:!0,sidebar:"docs"},{path:"/docs/themes",component:d("/docs/themes","82b"),exact:!0,sidebar:"docs"},{path:"/docs/topic_separator",component:d("/docs/topic_separator","ac3"),exact:!0,sidebar:"docs"},{path:"/docs/topics",component:d("/docs/topics","704"),exact:!0,sidebar:"docs"}]}]}]},{path:"/",component:d("/","d94"),exact:!0},{path:"*",component:d("*")}]},6125:(e,t,n)=>{"use strict";n.d(t,{o:()=>a,x:()=>i});var r=n(6540),o=n(4848),a=r.createContext(!1);function i(e){var t=e.children,n=(0,r.useState)(!1),i=n[0],l=n[1];return(0,r.useEffect)((function(){l(!0)}),[]),(0,o.jsx)(a.Provider,{value:i,children:t})}},8536:(e,t,n)=>{"use strict";var r=n(6540),o=n(5338),a=n(4625),i=n(545),l=n(8193);const s=[n(119),n(6134),n(6294),n(1043)];var u=n(8328),c=n(6347),d=n(2831),f=n(4848);function p(e){var t=e.children;return(0,f.jsx)(f.Fragment,{children:t})}var m=n(5260),h=n(4586),g=n(6025),b=n(6342),y=n(9024),v=n(2131),w=n(4090),k=n(2967),x=n(440),S=n(1463);function _(){var e=(0,h.A)().i18n,t=e.currentLocale,n=e.defaultLocale,r=e.localeConfigs,o=(0,v.o)(),a=r[t].htmlLang,i=function(e){return e.replace("-","_")};return(0,f.jsxs)(m.A,{children:[Object.entries(r).map((function(e){var t=e[0],n=e[1].htmlLang;return(0,f.jsx)("link",{rel:"alternate",href:o.createUrl({locale:t,fullyQualified:!0}),hrefLang:n},t)})),(0,f.jsx)("link",{rel:"alternate",href:o.createUrl({locale:n,fullyQualified:!0}),hrefLang:"x-default"}),(0,f.jsx)("meta",{property:"og:locale",content:i(a)}),Object.values(r).filter((function(e){return a!==e.htmlLang})).map((function(e){return(0,f.jsx)("meta",{property:"og:locale:alternate",content:i(e.htmlLang)},"meta-og-"+e.htmlLang)}))]})}function E(e){var t=e.permalink,n=(0,h.A)().siteConfig.url,r=function(){var e=(0,h.A)().siteConfig,t=e.url,n=e.baseUrl,r=e.trailingSlash,o=(0,c.zy)().pathname;return t+(0,x.applyTrailingSlash)((0,g.A)(o),{trailingSlash:r,baseUrl:n})}(),o=t?""+n+t:r;return(0,f.jsxs)(m.A,{children:[(0,f.jsx)("meta",{property:"og:url",content:o}),(0,f.jsx)("link",{rel:"canonical",href:o})]})}function C(){var e=(0,h.A)().i18n.currentLocale,t=(0,b.p)(),n=t.metadata,r=t.image;return(0,f.jsxs)(f.Fragment,{children:[(0,f.jsxs)(m.A,{children:[(0,f.jsx)("meta",{name:"twitter:card",content:"summary_large_image"}),(0,f.jsx)("body",{className:w.w})]}),r&&(0,f.jsx)(y.be,{image:r}),(0,f.jsx)(E,{}),(0,f.jsx)(_,{}),(0,f.jsx)(S.A,{tag:k.Cy,locale:e}),(0,f.jsx)(m.A,{children:n.map((function(e,t){return(0,f.jsx)("meta",Object.assign({},e),t)}))})]})}var A=new Map;function T(e){if(A.has(e.pathname))return Object.assign({},e,{pathname:A.get(e.pathname)});if((0,d.u)(u.A,e.pathname).some((function(e){return!0===e.route.exact})))return A.set(e.pathname,e.pathname),e;var t=e.pathname.trim().replace(/(?:\/index)?\.html$/,"")||"/";return A.set(e.pathname,t),Object.assign({},e,{pathname:t})}var j=n(6125),R=n(6988),O=n(6711),L=n(205);function N(e){for(var t=arguments.length,n=new Array(t>1?t-1:0),r=1;rYour Docusaurus site did not load properly.
\nA very common reason is a wrong site baseUrl configuration.
\nCurrent configured baseUrl = '+e+" "+("/"===e?" (default value)":"")+'
\nWe suggest trying baseUrl =
\n\n'}(e)).replace(/{"use strict";n.d(t,{o:()=>d,l:()=>f});var r=n(6540),o=n(4784);const a=JSON.parse('{"docusaurus-plugin-content-docs":{"default":{"path":"/docs","versions":[{"name":"current","label":"Next","isLast":true,"path":"/docs","mainDocId":"index","docs":[{"id":"aliases","path":"/docs/aliases","sidebar":"docs"},{"id":"args","path":"/docs/args","sidebar":"docs"},{"id":"base_class","path":"/docs/base_class","sidebar":"docs"},{"id":"command_discovery_strategies","path":"/docs/command_discovery_strategies","sidebar":"docs"},{"id":"command_execution","path":"/docs/command_execution","sidebar":"docs"},{"id":"commands","path":"/docs/commands","sidebar":"docs"},{"id":"config","path":"/docs/config","sidebar":"docs"},{"id":"debugging","path":"/docs/debugging","sidebar":"docs"},{"id":"error_handling","path":"/docs/error_handling","sidebar":"docs"},{"id":"esm","path":"/docs/esm","sidebar":"docs"},{"id":"examples","path":"/docs/examples","sidebar":"docs"},{"id":"external_links","path":"/docs/external_links","sidebar":"docs"},{"id":"faqs","path":"/docs/faqs","sidebar":"docs"},{"id":"features","path":"/docs/features","sidebar":"docs"},{"id":"feedback","path":"/docs/feedback","sidebar":"docs"},{"id":"flags","path":"/docs/flags","sidebar":"docs"},{"id":"flexible_taxonomy","path":"/docs/flexible_taxonomy","sidebar":"docs"},{"id":"generator_commands","path":"/docs/generator_commands","sidebar":"docs"},{"id":"global_flags","path":"/docs/global_flags","sidebar":"docs"},{"id":"help_classes","path":"/docs/help_classes","sidebar":"docs"},{"id":"hooks","path":"/docs/hooks","sidebar":"docs"},{"id":"how_we_work","path":"/docs/how_we_work","sidebar":"docs"},{"id":"index","path":"/docs/"},{"id":"introduction","path":"/docs/introduction","sidebar":"docs"},{"id":"jit_plugins","path":"/docs/jit_plugins","sidebar":"docs"},{"id":"json","path":"/docs/json","sidebar":"docs"},{"id":"notifications","path":"/docs/notifications","sidebar":"docs"},{"id":"nsis-installer_customization","path":"/docs/nsis-installer_customization","sidebar":"docs"},{"id":"plugin_loading","path":"/docs/plugin_loading","sidebar":"docs"},{"id":"plugins","path":"/docs/plugins","sidebar":"docs"},{"id":"prompting","path":"/docs/prompting","sidebar":"docs"},{"id":"related_repos","path":"/docs/related_repos","sidebar":"docs"},{"id":"releasing","path":"/docs/releasing","sidebar":"docs"},{"id":"running_programmatically","path":"/docs/running_programmatically","sidebar":"docs"},{"id":"single_command_cli","path":"/docs/single_command_cli","sidebar":"docs"},{"id":"spinner","path":"/docs/spinner","sidebar":"docs"},{"id":"table","path":"/docs/table","sidebar":"docs"},{"id":"testing","path":"/docs/testing","sidebar":"docs"},{"id":"themes","path":"/docs/themes","sidebar":"docs"},{"id":"topic_separator","path":"/docs/topic_separator","sidebar":"docs"},{"id":"topics","path":"/docs/topics","sidebar":"docs"}],"draftIds":[],"sidebars":{"docs":{"link":{"path":"/docs/introduction","label":"introduction"}}}}],"breadcrumbs":true}}}'),i=JSON.parse('{"defaultLocale":"en","locales":["en"],"path":"i18n","currentLocale":"en","localeConfigs":{"en":{"label":"English","direction":"ltr","htmlLang":"en","calendar":"gregory","path":"en"}}}');var l=n(2654);const s=JSON.parse('{"docusaurusVersion":"3.1.1","pluginVersions":{"docusaurus-plugin-content-docs":{"type":"package","name":"@docusaurus/plugin-content-docs","version":"3.1.1"},"docusaurus-plugin-content-blog":{"type":"package","name":"@docusaurus/plugin-content-blog","version":"3.1.1"},"docusaurus-plugin-content-pages":{"type":"package","name":"@docusaurus/plugin-content-pages","version":"3.1.1"},"docusaurus-plugin-sitemap":{"type":"package","name":"@docusaurus/plugin-sitemap","version":"3.1.1"},"docusaurus-theme-classic":{"type":"package","name":"@docusaurus/theme-classic","version":"3.1.1"},"docusaurus-theme-search-algolia":{"type":"package","name":"@docusaurus/theme-search-algolia","version":"3.1.1"}}}');var u=n(4848),c={siteConfig:o.default,siteMetadata:s,globalData:a,i18n:i,codeTranslations:l},d=r.createContext(c);function f(e){var t=e.children;return(0,u.jsx)(d.Provider,{value:c,children:t})}},7489:(e,t,n)=>{"use strict";n.d(t,{A:()=>m});var r=n(6711),o=n(6540),a=n(8193),i=n(5260),l=n(440),s=n(9201),u=n(4848);function c(e){var t=e.error,n=e.tryAgain;return(0,u.jsxs)("div",{style:{display:"flex",flexDirection:"column",justifyContent:"center",alignItems:"flex-start",minHeight:"100vh",width:"100%",maxWidth:"80ch",fontSize:"20px",margin:"0 auto",padding:"1rem"},children:[(0,u.jsx)("h1",{style:{fontSize:"3rem"},children:"This page crashed"}),(0,u.jsx)("button",{type:"button",onClick:n,style:{margin:"1rem 0",fontSize:"2rem",cursor:"pointer",borderRadius:20,padding:"1rem"},children:"Try again"}),(0,u.jsx)(d,{error:t})]})}function d(e){var t=e.error,n=(0,l.getErrorCausalChain)(t).map((function(e){return e.message})).join("\n\nCause:\n");return(0,u.jsx)("p",{style:{whiteSpace:"pre-wrap"},children:n})}function f(e){var t=e.error,n=e.tryAgain;return(0,u.jsxs)(m,{fallback:function(){return(0,u.jsx)(c,{error:t,tryAgain:n})},children:[(0,u.jsx)(i.A,{children:(0,u.jsx)("title",{children:"Page Error"})}),(0,u.jsx)(s.A,{children:(0,u.jsx)(c,{error:t,tryAgain:n})})]})}var p=function(e){return(0,u.jsx)(f,Object.assign({},e))},m=function(e){function t(t){var n;return(n=e.call(this,t)||this).state={error:null},n}(0,r.A)(t,e);var n=t.prototype;return n.componentDidCatch=function(e){a.A.canUseDOM&&this.setState({error:e})},n.render=function(){var e=this,t=this.props.children,n=this.state.error;if(n){var r,o={error:n,tryAgain:function(){return e.setState({error:null})}};return(null!=(r=this.props.fallback)?r:p)(o)}return null!=t?t:null},t}(o.Component)},8193:(e,t,n)=>{"use strict";n.d(t,{A:()=>o});var r="undefined"!=typeof window&&"document"in window&&"createElement"in window.document;const o={canUseDOM:r,canUseEventListeners:r&&("addEventListener"in window||"attachEvent"in window),canUseIntersectionObserver:r&&"IntersectionObserver"in window,canUseViewport:r&&"screen"in window}},5260:(e,t,n)=>{"use strict";n.d(t,{A:()=>a});n(6540);var r=n(545),o=n(4848);function a(e){return(0,o.jsx)(r.mg,Object.assign({},e))}},8774:(e,t,n)=>{"use strict";n.d(t,{A:()=>h});var r=n(1367),o=n(6540),a=n(4625),i=n(440),l=n(4586),s=n(6654),u=n(8193),c=n(3427),d=n(6025),f=n(4848),p=["isNavLink","to","href","activeClassName","isActive","data-noBrokenLinkCheck","autoAddBaseUrl"];function m(e,t){var n,m,h=e.isNavLink,g=e.to,b=e.href,y=e.activeClassName,v=e.isActive,w=e["data-noBrokenLinkCheck"],k=e.autoAddBaseUrl,x=void 0===k||k,S=(0,r.A)(e,p),_=(0,l.A)().siteConfig,E=_.trailingSlash,C=_.baseUrl,A=(0,d.h)().withBaseUrl,T=(0,c.A)(),j=(0,o.useRef)(null);(0,o.useImperativeHandle)(t,(function(){return j.current}));var R=g||b;var O,L=(0,s.A)(R),N=null==R?void 0:R.replace("pathname://",""),P=void 0!==N?(O=N,x&&function(e){return e.startsWith("/")}(O)?A(O):O):void 0;P&&L&&(P=(0,i.applyTrailingSlash)(P,{trailingSlash:E,baseUrl:C}));var D=(0,o.useRef)(!1),I=h?a.k2:a.N_,M=u.A.canUseIntersectionObserver,F=(0,o.useRef)(),B=function(){D.current||null==P||(window.docusaurus.preload(P),D.current=!0)};(0,o.useEffect)((function(){return!M&&L&&null!=P&&window.docusaurus.prefetch(P),function(){M&&F.current&&F.current.disconnect()}}),[F,P,M,L]);var z=null!=(n=null==(m=P)?void 0:m.startsWith("#"))&&n,U=!S.target||"_self"===S.target,$=!P||!L||!U||z;return w||!z&&$||T.collectLink(P),S.id&&T.collectAnchor(S.id),$?(0,f.jsx)("a",Object.assign({ref:j,href:P},R&&!L&&{target:"_blank",rel:"noopener noreferrer"},S)):(0,f.jsx)(I,Object.assign({},S,{onMouseEnter:B,onTouchStart:B,innerRef:function(e){j.current=e,M&&e&&L&&(F.current=new window.IntersectionObserver((function(t){t.forEach((function(t){e===t.target&&(t.isIntersecting||t.intersectionRatio>0)&&(F.current.unobserve(e),F.current.disconnect(),null!=P&&window.docusaurus.prefetch(P))}))})),F.current.observe(e))},to:P},h&&{isActive:v,activeClassName:y}))}const h=o.forwardRef(m)},1312:(e,t,n)=>{"use strict";n.d(t,{A:()=>u,T:()=>s});var r=n(6540),o=n(4848);function a(e,t){var n=e.split(/(\{\w+\})/).map((function(e,n){if(n%2==1){var r=null==t?void 0:t[e.slice(1,-1)];if(void 0!==r)return r}return e}));return n.some((function(e){return(0,r.isValidElement)(e)}))?n.map((function(e,t){return(0,r.isValidElement)(e)?r.cloneElement(e,{key:t}):e})).filter((function(e){return""!==e})):n.join("")}var i=n(2654);function l(e){var t,n,r=e.id,o=e.message;if(void 0===r&&void 0===o)throw new Error("Docusaurus translation declarations must have at least a translation id or a default translation message");return null!=(t=null!=(n=i[null!=r?r:o])?n:o)?t:r}function s(e,t){return a(l({message:e.message,id:e.id}),t)}function u(e){var t=e.children,n=e.id,r=e.values;if(t&&"string"!=typeof t)throw console.warn("Illegal'};function o(e,t,n){return e
.comment can become .namespace--comment) or replace them with your defined ones (like .editor__comment). You can even add new classes.",owner:"dvkndn",noCSS:!0},"file-highlight":{title:"File Highlight",description:"Fetch external files and highlight them with Prism. Used on the Prism website itself.",noCSS:!0},"show-language":{title:"Show Language",description:"Display the highlighted language in code blocks (inline code does not show the label).",owner:"nauzilus",noCSS:!0,require:"toolbar"},"jsonp-highlight":{title:"JSONP Highlight",description:"Fetch content with JSONP and highlight some interesting content (e.g. GitHub/Gists or Bitbucket API).",noCSS:!0,owner:"nauzilus"},"highlight-keywords":{title:"Highlight Keywords",description:"Adds special CSS classes for each keyword for fine-grained highlighting.",owner:"vkbansal",noCSS:!0},"remove-initial-line-feed":{title:"Remove initial line feed",description:"Removes the initial line feed in code blocks.",owner:"Golmote",noCSS:!0},"inline-color":{title:"Inline color",description:"Adds a small inline preview for colors in style sheets.",require:"css-extras",owner:"RunDevelopment"},previewers:{title:"Previewers",description:"Previewers for angles, colors, gradients, easing and time.",require:"css-extras",owner:"Golmote"},autoloader:{title:"Autoloader",description:"Automatically loads the needed languages to highlight the code blocks.",owner:"Golmote",noCSS:!0},"keep-markup":{title:"Keep Markup",description:"Prevents custom markup from being dropped out during highlighting.",owner:"Golmote",optional:"normalize-whitespace",noCSS:!0},"command-line":{title:"Command Line",description:"Display a command line with a prompt and, optionally, the output/response from the commands.",owner:"chriswells0"},"unescaped-markup":{title:"Unescaped Markup",description:"Write markup without having to escape anything."},"normalize-whitespace":{title:"Normalize Whitespace",description:"Supports multiple operations to normalize whitespace in code blocks.",owner:"zeitgeist87",optional:"unescaped-markup",noCSS:!0},"data-uri-highlight":{title:"Data-URI Highlight",description:"Highlights data-URI contents.",owner:"Golmote",noCSS:!0},toolbar:{title:"Toolbar",description:"Attach a toolbar for plugins to easily register buttons on the top of a code block.",owner:"mAAdhaTTah"},"copy-to-clipboard":{title:"Copy to Clipboard Button",description:"Add a button that copies the code block to the clipboard when clicked.",owner:"mAAdhaTTah",require:"toolbar",noCSS:!0},"download-button":{title:"Download Button",description:"A button in the toolbar of a code block adding a convenient way to download a code file.",owner:"Golmote",require:"toolbar",noCSS:!0},"match-braces":{title:"Match braces",description:"Highlights matching braces.",owner:"RunDevelopment"},"diff-highlight":{title:"Diff Highlight",description:"Highlights the code inside diff blocks.",owner:"RunDevelopment",require:"diff"},"filter-highlight-all":{title:"Filter highlightAll",description:"Filters the elements the highlightAll and highlightAllUnder methods actually highlight.",owner:"RunDevelopment",noCSS:!0},treeview:{title:"Treeview",description:"A language with special styles to highlight file system tree structures.",owner:"Golmote"}}})},8722:(e,t,n)=>{const r=n(6969),o=n(8380),a=new Set;function i(e){void 0===e?e=Object.keys(r.languages).filter((e=>"meta"!=e)):Array.isArray(e)||(e=[e]);const t=[...a,...Object.keys(Prism.languages)];o(r,e,t).load((e=>{if(!(e in r.languages))return void(i.silent||console.warn("Language does not exist: "+e));const t="./prism-"+e;delete n.c[n(3157).resolve(t)],delete Prism.languages[e],n(3157)(t),a.add(e)}))}i.silent=!1,e.exports=i},9700:()=>{!function(e){function t(e,t){return"___"+e.toUpperCase()+t+"___"}Object.defineProperties(e.languages["markup-templating"]={},{buildPlaceholders:{value:function(n,r,o,a){if(n.language===r){var i=n.tokenStack=[];n.code=n.code.replace(o,(function(e){if("function"==typeof a&&!a(e))return e;for(var o,l=i.length;-1!==n.code.indexOf(o=t(r,l));)++l;return i[l]=e,o})),n.grammar=e.languages.markup}}},tokenizePlaceholders:{value:function(n,r){if(n.language===r&&n.tokenStack){n.grammar=e.languages[r];var o=0,a=Object.keys(n.tokenStack);!function i(l){for(var s=0;sYour Docusaurus site did not load properly.
\nA very common reason is a wrong site baseUrl configuration.
\nCurrent configured baseUrl = '+e+" "+("/"===e?" (default value)":"")+'
\nWe suggest trying baseUrl =
\n\n'}(e)).replace(/{"use strict";n.d(t,{o:()=>d,l:()=>f});var r=n(6540),o=n(4784);const a=JSON.parse('{"docusaurus-plugin-content-docs":{"default":{"path":"/docs","versions":[{"name":"current","label":"Next","isLast":true,"path":"/docs","mainDocId":"index","docs":[{"id":"aliases","path":"/docs/aliases","sidebar":"docs"},{"id":"args","path":"/docs/args","sidebar":"docs"},{"id":"base_class","path":"/docs/base_class","sidebar":"docs"},{"id":"command_discovery_strategies","path":"/docs/command_discovery_strategies","sidebar":"docs"},{"id":"command_execution","path":"/docs/command_execution","sidebar":"docs"},{"id":"commands","path":"/docs/commands","sidebar":"docs"},{"id":"config","path":"/docs/config","sidebar":"docs"},{"id":"debugging","path":"/docs/debugging","sidebar":"docs"},{"id":"error_handling","path":"/docs/error_handling","sidebar":"docs"},{"id":"esm","path":"/docs/esm","sidebar":"docs"},{"id":"examples","path":"/docs/examples","sidebar":"docs"},{"id":"external_links","path":"/docs/external_links","sidebar":"docs"},{"id":"faqs","path":"/docs/faqs","sidebar":"docs"},{"id":"features","path":"/docs/features","sidebar":"docs"},{"id":"feedback","path":"/docs/feedback","sidebar":"docs"},{"id":"flags","path":"/docs/flags","sidebar":"docs"},{"id":"flexible_taxonomy","path":"/docs/flexible_taxonomy","sidebar":"docs"},{"id":"generator_commands","path":"/docs/generator_commands","sidebar":"docs"},{"id":"global_flags","path":"/docs/global_flags","sidebar":"docs"},{"id":"help_classes","path":"/docs/help_classes","sidebar":"docs"},{"id":"hooks","path":"/docs/hooks","sidebar":"docs"},{"id":"how_we_work","path":"/docs/how_we_work","sidebar":"docs"},{"id":"index","path":"/docs/"},{"id":"introduction","path":"/docs/introduction","sidebar":"docs"},{"id":"jit_plugins","path":"/docs/jit_plugins","sidebar":"docs"},{"id":"json","path":"/docs/json","sidebar":"docs"},{"id":"notifications","path":"/docs/notifications","sidebar":"docs"},{"id":"nsis-installer_customization","path":"/docs/nsis-installer_customization","sidebar":"docs"},{"id":"plugin_loading","path":"/docs/plugin_loading","sidebar":"docs"},{"id":"plugins","path":"/docs/plugins","sidebar":"docs"},{"id":"prompting","path":"/docs/prompting","sidebar":"docs"},{"id":"related_repos","path":"/docs/related_repos","sidebar":"docs"},{"id":"releasing","path":"/docs/releasing","sidebar":"docs"},{"id":"running_programmatically","path":"/docs/running_programmatically","sidebar":"docs"},{"id":"single_command_cli","path":"/docs/single_command_cli","sidebar":"docs"},{"id":"spinner","path":"/docs/spinner","sidebar":"docs"},{"id":"table","path":"/docs/table","sidebar":"docs"},{"id":"testing","path":"/docs/testing","sidebar":"docs"},{"id":"themes","path":"/docs/themes","sidebar":"docs"},{"id":"topic_separator","path":"/docs/topic_separator","sidebar":"docs"},{"id":"topics","path":"/docs/topics","sidebar":"docs"}],"draftIds":[],"sidebars":{"docs":{"link":{"path":"/docs/introduction","label":"introduction"}}}}],"breadcrumbs":true}}}'),i=JSON.parse('{"defaultLocale":"en","locales":["en"],"path":"i18n","currentLocale":"en","localeConfigs":{"en":{"label":"English","direction":"ltr","htmlLang":"en","calendar":"gregory","path":"en"}}}');var l=n(2654);const s=JSON.parse('{"docusaurusVersion":"3.1.1","pluginVersions":{"docusaurus-plugin-content-docs":{"type":"package","name":"@docusaurus/plugin-content-docs","version":"3.1.1"},"docusaurus-plugin-content-blog":{"type":"package","name":"@docusaurus/plugin-content-blog","version":"3.1.1"},"docusaurus-plugin-content-pages":{"type":"package","name":"@docusaurus/plugin-content-pages","version":"3.1.1"},"docusaurus-plugin-sitemap":{"type":"package","name":"@docusaurus/plugin-sitemap","version":"3.1.1"},"docusaurus-theme-classic":{"type":"package","name":"@docusaurus/theme-classic","version":"3.1.1"},"docusaurus-theme-search-algolia":{"type":"package","name":"@docusaurus/theme-search-algolia","version":"3.1.1"}}}');var c=n(4848),u={siteConfig:o.default,siteMetadata:s,globalData:a,i18n:i,codeTranslations:l},d=r.createContext(u);function f(e){var t=e.children;return(0,c.jsx)(d.Provider,{value:u,children:t})}},7489:(e,t,n)=>{"use strict";n.d(t,{A:()=>m});var r=n(6711),o=n(6540),a=n(8193),i=n(5260),l=n(440),s=n(9201),c=n(4848);function u(e){var t=e.error,n=e.tryAgain;return(0,c.jsxs)("div",{style:{display:"flex",flexDirection:"column",justifyContent:"center",alignItems:"flex-start",minHeight:"100vh",width:"100%",maxWidth:"80ch",fontSize:"20px",margin:"0 auto",padding:"1rem"},children:[(0,c.jsx)("h1",{style:{fontSize:"3rem"},children:"This page crashed"}),(0,c.jsx)("button",{type:"button",onClick:n,style:{margin:"1rem 0",fontSize:"2rem",cursor:"pointer",borderRadius:20,padding:"1rem"},children:"Try again"}),(0,c.jsx)(d,{error:t})]})}function d(e){var t=e.error,n=(0,l.getErrorCausalChain)(t).map((function(e){return e.message})).join("\n\nCause:\n");return(0,c.jsx)("p",{style:{whiteSpace:"pre-wrap"},children:n})}function f(e){var t=e.error,n=e.tryAgain;return(0,c.jsxs)(m,{fallback:function(){return(0,c.jsx)(u,{error:t,tryAgain:n})},children:[(0,c.jsx)(i.A,{children:(0,c.jsx)("title",{children:"Page Error"})}),(0,c.jsx)(s.A,{children:(0,c.jsx)(u,{error:t,tryAgain:n})})]})}var p=function(e){return(0,c.jsx)(f,Object.assign({},e))},m=function(e){function t(t){var n;return(n=e.call(this,t)||this).state={error:null},n}(0,r.A)(t,e);var n=t.prototype;return n.componentDidCatch=function(e){a.A.canUseDOM&&this.setState({error:e})},n.render=function(){var e=this,t=this.props.children,n=this.state.error;if(n){var r,o={error:n,tryAgain:function(){return e.setState({error:null})}};return(null!=(r=this.props.fallback)?r:p)(o)}return null!=t?t:null},t}(o.Component)},8193:(e,t,n)=>{"use strict";n.d(t,{A:()=>o});var r="undefined"!=typeof window&&"document"in window&&"createElement"in window.document;const o={canUseDOM:r,canUseEventListeners:r&&("addEventListener"in window||"attachEvent"in window),canUseIntersectionObserver:r&&"IntersectionObserver"in window,canUseViewport:r&&"screen"in window}},5260:(e,t,n)=>{"use strict";n.d(t,{A:()=>a});n(6540);var r=n(545),o=n(4848);function a(e){return(0,o.jsx)(r.mg,Object.assign({},e))}},8774:(e,t,n)=>{"use strict";n.d(t,{A:()=>h});var r=n(1367),o=n(6540),a=n(4625),i=n(440),l=n(4586),s=n(6654),c=n(8193),u=n(3427),d=n(6025),f=n(4848),p=["isNavLink","to","href","activeClassName","isActive","data-noBrokenLinkCheck","autoAddBaseUrl"];function m(e,t){var n,m,h=e.isNavLink,g=e.to,b=e.href,y=e.activeClassName,v=e.isActive,w=e["data-noBrokenLinkCheck"],k=e.autoAddBaseUrl,x=void 0===k||k,S=(0,r.A)(e,p),_=(0,l.A)().siteConfig,E=_.trailingSlash,C=_.baseUrl,A=(0,d.h)().withBaseUrl,T=(0,u.A)(),j=(0,o.useRef)(null);(0,o.useImperativeHandle)(t,(function(){return j.current}));var R=g||b;var O,L=(0,s.A)(R),N=null==R?void 0:R.replace("pathname://",""),P=void 0!==N?(O=N,x&&function(e){return e.startsWith("/")}(O)?A(O):O):void 0;P&&L&&(P=(0,i.applyTrailingSlash)(P,{trailingSlash:E,baseUrl:C}));var D=(0,o.useRef)(!1),I=h?a.k2:a.N_,M=c.A.canUseIntersectionObserver,F=(0,o.useRef)(),B=function(){D.current||null==P||(window.docusaurus.preload(P),D.current=!0)};(0,o.useEffect)((function(){return!M&&L&&null!=P&&window.docusaurus.prefetch(P),function(){M&&F.current&&F.current.disconnect()}}),[F,P,M,L]);var z=null!=(n=null==(m=P)?void 0:m.startsWith("#"))&&n,U=!S.target||"_self"===S.target,$=!P||!L||!U||z;return w||!z&&$||T.collectLink(P),S.id&&T.collectAnchor(S.id),$?(0,f.jsx)("a",Object.assign({ref:j,href:P},R&&!L&&{target:"_blank",rel:"noopener noreferrer"},S)):(0,f.jsx)(I,Object.assign({},S,{onMouseEnter:B,onTouchStart:B,innerRef:function(e){j.current=e,M&&e&&L&&(F.current=new window.IntersectionObserver((function(t){t.forEach((function(t){e===t.target&&(t.isIntersecting||t.intersectionRatio>0)&&(F.current.unobserve(e),F.current.disconnect(),null!=P&&window.docusaurus.prefetch(P))}))})),F.current.observe(e))},to:P},h&&{isActive:v,activeClassName:y}))}const h=o.forwardRef(m)},1312:(e,t,n)=>{"use strict";n.d(t,{A:()=>c,T:()=>s});var r=n(6540),o=n(4848);function a(e,t){var n=e.split(/(\{\w+\})/).map((function(e,n){if(n%2==1){var r=null==t?void 0:t[e.slice(1,-1)];if(void 0!==r)return r}return e}));return n.some((function(e){return(0,r.isValidElement)(e)}))?n.map((function(e,t){return(0,r.isValidElement)(e)?r.cloneElement(e,{key:t}):e})).filter((function(e){return""!==e})):n.join("")}var i=n(2654);function l(e){var t,n,r=e.id,o=e.message;if(void 0===r&&void 0===o)throw new Error("Docusaurus translation declarations must have at least a translation id or a default translation message");return null!=(t=null!=(n=i[null!=r?r:o])?n:o)?t:r}function s(e,t){return a(l({message:e.message,id:e.id}),t)}function c(e){var t=e.children,n=e.id,r=e.values;if(t&&"string"!=typeof t)throw console.warn("Illegal'};function o(e,t,n){return e
.comment can become .namespace--comment) or replace them with your defined ones (like .editor__comment). You can even add new classes.",owner:"dvkndn",noCSS:!0},"file-highlight":{title:"File Highlight",description:"Fetch external files and highlight them with Prism. Used on the Prism website itself.",noCSS:!0},"show-language":{title:"Show Language",description:"Display the highlighted language in code blocks (inline code does not show the label).",owner:"nauzilus",noCSS:!0,require:"toolbar"},"jsonp-highlight":{title:"JSONP Highlight",description:"Fetch content with JSONP and highlight some interesting content (e.g. GitHub/Gists or Bitbucket API).",noCSS:!0,owner:"nauzilus"},"highlight-keywords":{title:"Highlight Keywords",description:"Adds special CSS classes for each keyword for fine-grained highlighting.",owner:"vkbansal",noCSS:!0},"remove-initial-line-feed":{title:"Remove initial line feed",description:"Removes the initial line feed in code blocks.",owner:"Golmote",noCSS:!0},"inline-color":{title:"Inline color",description:"Adds a small inline preview for colors in style sheets.",require:"css-extras",owner:"RunDevelopment"},previewers:{title:"Previewers",description:"Previewers for angles, colors, gradients, easing and time.",require:"css-extras",owner:"Golmote"},autoloader:{title:"Autoloader",description:"Automatically loads the needed languages to highlight the code blocks.",owner:"Golmote",noCSS:!0},"keep-markup":{title:"Keep Markup",description:"Prevents custom markup from being dropped out during highlighting.",owner:"Golmote",optional:"normalize-whitespace",noCSS:!0},"command-line":{title:"Command Line",description:"Display a command line with a prompt and, optionally, the output/response from the commands.",owner:"chriswells0"},"unescaped-markup":{title:"Unescaped Markup",description:"Write markup without having to escape anything."},"normalize-whitespace":{title:"Normalize Whitespace",description:"Supports multiple operations to normalize whitespace in code blocks.",owner:"zeitgeist87",optional:"unescaped-markup",noCSS:!0},"data-uri-highlight":{title:"Data-URI Highlight",description:"Highlights data-URI contents.",owner:"Golmote",noCSS:!0},toolbar:{title:"Toolbar",description:"Attach a toolbar for plugins to easily register buttons on the top of a code block.",owner:"mAAdhaTTah"},"copy-to-clipboard":{title:"Copy to Clipboard Button",description:"Add a button that copies the code block to the clipboard when clicked.",owner:"mAAdhaTTah",require:"toolbar",noCSS:!0},"download-button":{title:"Download Button",description:"A button in the toolbar of a code block adding a convenient way to download a code file.",owner:"Golmote",require:"toolbar",noCSS:!0},"match-braces":{title:"Match braces",description:"Highlights matching braces.",owner:"RunDevelopment"},"diff-highlight":{title:"Diff Highlight",description:"Highlights the code inside diff blocks.",owner:"RunDevelopment",require:"diff"},"filter-highlight-all":{title:"Filter highlightAll",description:"Filters the elements the highlightAll and highlightAllUnder methods actually highlight.",owner:"RunDevelopment",noCSS:!0},treeview:{title:"Treeview",description:"A language with special styles to highlight file system tree structures.",owner:"Golmote"}}})},8722:(e,t,n)=>{const r=n(6969),o=n(8380),a=new Set;function i(e){void 0===e?e=Object.keys(r.languages).filter((e=>"meta"!=e)):Array.isArray(e)||(e=[e]);const t=[...a,...Object.keys(Prism.languages)];o(r,e,t).load((e=>{if(!(e in r.languages))return void(i.silent||console.warn("Language does not exist: "+e));const t="./prism-"+e;delete n.c[n(3157).resolve(t)],delete Prism.languages[e],n(3157)(t),a.add(e)}))}i.silent=!1,e.exports=i},9700:()=>{!function(e){function t(e,t){return"___"+e.toUpperCase()+t+"___"}Object.defineProperties(e.languages["markup-templating"]={},{buildPlaceholders:{value:function(n,r,o,a){if(n.language===r){var i=n.tokenStack=[];n.code=n.code.replace(o,(function(e){if("function"==typeof a&&!a(e))return e;for(var o,l=i.length;-1!==n.code.indexOf(o=t(r,l));)++l;return i[l]=e,o})),n.grammar=e.languages.markup}}},tokenizePlaceholders:{value:function(n,r){if(n.language===r&&n.tokenStack){n.grammar=e.languages[r];var o=0,a=Object.keys(n.tokenStack);!function i(l){for(var s=0;s