oclif / oclif.github.io

docs for oclif

oclif.io

Developing Instructions

$ git clone https://github.com/oclif/oclif.github.io
$ cd oclif.github.io/website
$ yarn install
$ yarn start

oclif.github.io's Issues

update multiple args & static

Requires: oclif/oclif#234

High Severity Vulnerability which cannot be fixed without --force

When creating a multiline CLI based on the Quick Start Instructions, I received a warning, "found 1 high severity vulnerability" which, of course, isn't great.

I had to use --force with npm audit fix to eliminate it which broke my new CLI. :-(

update docs for errors outside of a command

In docs/command.md under "Command Methods", it is indicated that CLIError can be used directly when one needs to throw an error outside of a command. However, while CLIError does take the same options as errors does, they are not processed properly when an error is thrown via CLIError because the handle method does not call applyPrettyPrintOptions like Command.error does.

Since Command.error just proxies to Errors.error it would seem that Errors.error would be a better alternative to Command.errors than CLIError is.

If there is some reason we should not be using Errors.error directly, perhaps we could note that the options fields aren't used if applyPrettyPrintOptions is not also called.

where can I find the v1 docs?

Normally if docs are updated, the previous version is kept accessible, not everyone can upgrade within a short time frame, and will need to refer to the v1 docs in the meantime.

I understand that the website wasn't designed for multiple versions so that is fine.

I can refer to the v1 docs from a tag, but I can't find any tags in this repo.

add clarification to init hook example that the command id passed is not yet "found"

Custom Base Command class: 'flags' does not exist on type 'default'

Issue with docs: https://github.com/oclif/oclif.github.io/blob/docs/docs/base_class.md

Copying the code from the above, I get the following error:
Property 'flags' does not exist on type 'default'. Did you mean to access the static member 'default.flags' instead?

Is it possible to modify the flags within the init() of the base class?

Improve and finalize ESM documentation

Once we get close to finishing ESM support we need to update the documentation to give the official guidance on how to use ESM for plugins and how to migrate a CLI from CJS to ESM

Things to include:

• linking ESM plugins into CJS root plugins will not work
• considerations around using --loader ts-node/esm in bin/dev and bin/run

Following esm guide leads to "SyntaxError: Cannot use import statement outside a module" for dev.js

Problem:

Using https://oclif.io/docs/esm to enable ESM leads to

SyntaxError: Cannot use import statement outside a module
    at internalCompileFunction (node:internal/vm:73:18)
    at wrapSafe (node:internal/modules/cjs/loader:1187:20)
    at Module._compile (node:internal/modules/cjs/loader:1231:27)
    at Module._extensions..js (node:internal/modules/cjs/loader:1321:10)
    at Module.load (node:internal/modules/cjs/loader:1125:32)
    at Module._load (node:internal/modules/cjs/loader:965:12)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/translators:165:29)
    at ModuleJob.run (node:internal/modules/esm/module_job:192:25)

I adjusted the dev.js accordingly to the second point but haven't used on of the examples from the third point.

After adding "type": "module", to the package.json I get (node:1200) [ERR_UNKNOWN_FILE_EXTENSION] TypeError Plugin: esm-test: Unknown file extension ".ts" for /path/tp/oclif/project/src/commands/hello/world.ts

To fix that I had to use the ts-node esm loader. After replacing #!/usr/bin/env ts-node with #!/usr/bin/env node --loader ts-node/esm

After that it worked for me.

Solution:

1. Adding "type": "module", to package.json
2. Replacing #!/usr/bin/env ts-node with #!/usr/bin/env node --loader ts-node/esm in dev.js

Easy Fix Bug

There is a spelling mistake in the docs:

oclif.github.io/website/blog/2020-05-05-introducing-custom-help-classes.md

Line 38 in 67a193e

## Separating TOPICS & COMMANDS in the new deafult `Help` class

Do you have any sample code where flags are non static?

Lots of my commands share the same code and set of flags with minor differences. I want to able to define flags in my base class and just override it in some of super classes.
Instead of: const {flags} = this.parse(Get) I want to write something like const {flags} = this.parse(this.getFlags()}. Command classes will sometimes override getFlags() method inherited from base class. I have tried it but I couldn't get rid of all Typescript problems.
Thanks for any help.

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please delete the greenkeeper/initial branch in this repository, and then remove and re-add this repository to the Greenkeeper App’s white list on Github. You'll find this list on your repo or organization’s settings page, under Installed GitHub Apps.

make it clear that plugin-help is included in all CLI's currently

Ref oclif/plugin-help#50

Quick Start Instructions for Multi-line CLI are incorrect

Same corrections as I suggested for the single line CLI

Change ./bin/run to .\bin\run and change the file extension for index.js! to index.ts (ts with no exclamation point).

Building your own plugin documentation bug

The documentation on building your own plugin appears to be incorrect:

Specifically:

Run npx oclif plugin mynewplugin to create a plugin in a new directory. This will come with a sample command called hello.

The command npx oclif plugin mynewplugin did not work for me, I get the error message:

Warning: plugin mynewplugin is not a oclif command.

Better getting started tutorial?

Describe the issue

I had a tough time figuring out where to start with oclif. The CLI generator created a whole project but then I was left to poke through the docs and figure out what to do next, how the flags work, etc. So I did all that and wrote a tutorial in the process:

https://www.joshcanhelp.com/oclif/

It's based on a new oclif init command that's currently in PR (oclif/oclif#1358) but, once that's merged, I think it would be a much better introduction than what's there now. You're welcome to use it as-is or with edits, Markdown is here. I would appreciate attribution, if you're willing, but not required.

document release process in README

this.flags vs static flags

Hi,

I noticed in the Custom Base Class docs, there is a static flags and this.flags.:

    static flags = {
        loglevel: flags.string({ options: ['error', 'warn', 'info', 'debug'] })
    }
....
    async init() {
        // do some initialization
        const { flags } = this.parse(this.constructor)
        this.flags = flags
    }

Is that code in init correct? If it is, it sure if confusing. There is a lot of shadowing with the flags variable:

• static flags
• flags import from @oclif/command
• this.flags
• const { flags } = this.parse(this.constructor)

I just wanted to check if the this.flags was intentional. And if so, maybe comment about (at least my) confusion.
Also, I am not sure what exactly is "required" for the base command class. Does one even need the init method? Or can it be simply used for flags aggregation?

Thanks

Documentation Doesn't Mention Rebuilding After Generating a New Command

I generated a new CLI and it worked however after that every command I generated for that CLI wasn't being found. I got an idea to rebuild (npm run build) the code and it worked after that. This wasn't mentioned in the present docs.

The docs here and here do not mention rebuilding (npm run build) after generating a new command for an existing CLI. I think that should be added

How to create single cli using oclif v2

We know oclif v2 remove single cli generate, see: oclif/oclif#563

so we have created a multi cli project.

but the docs doesn't tell us how to change code of oclif v2 multi cli to single cli, maybe alias or default?

Update favicon

It looks like the docs site favicon is an old default favicon from Docusaurus. Since Oclif has its own logo, would that work as a favicon? Even just an oclif-green >_ would be better. 😄

cli.action.start params

the cli-ux action.start has a different function signature than the one listed. See their readme which reads

// show on stdout instead of stderr
cli.action.start('starting a process', 'initializing', {stdout: true})

OCLIF architecture diagram outdated

After creating telemetry for the Heroku CLI which uses OCLIF, some discoveries about the OCLIF architecture were made that aren't present in the current OCLIF architecture diagram.

In the diagram, if the COMMAND_NOT_FOUND hook is ran, it results in the exit process with the appropriate code process at the end of the diagram. The postrun hook is never fired.

The same thing applies to the Execute the version or help logic and display result to user process. It too never triggers the postrun hook and jumps straight to the Exit the process with appropriate exit code process.

It would be beneficial to update this diagram as it was what led to some bugs when creating the Heroku CLI telemetry that used this diagram as a reference.

hook error/exit docs incorrect

https://github.com/oclif/oclif.github.io/blob/docs/docs/hooks.md#L95

This suggests the use of this.error or this.exit however these methods are not available in my testing.

One alternative is to import @oclif/errors and do Errors.error(err, { exit: 1 }); for example.

Hook example for TypeScript does not compile

The basic hook example for TypeScript does not compile:

oclif.github.io/docs/hooks.md

Lines 9 to 17 in a08a668

	A basic hook looks like the following in TypeScript:
	```typescript
	import {Hook} from '@oclif/config'
	export default const hook: Hook<'init'> = async function (options) {
	console.log(`example init hook running before ${options.id}`)
	}
	```

src/cli/oclif.init.ts:3:16 - error TS1109: Expression expected.

3 export default const hook: Hook<'init'> = async function (options) {
                 ~~~~~

By removing the default keyword, the example works as expected for me.

The CLI Flags Explained links to 'Page Not Found'

I was reading through the docs and noticed the following link takes you to a Page Not Found page.

oclif.github.io/docs/flags.md

Line 162 in 1f455a0

See our blog post [CLI Flags Explained](../blog/2019/02/20/cli-flags-explained) for a deeper dive into CLI flags.

Instructions for single line CLI are incorrect

Change the instruction line: .\bin\run to ./bin/run (at least for windows 10)
Change the file extension in the next line from '.js' to '.ts' "hello world from .\src\index.ts"

Please improve Release docs with prerequisites

Do you want to request a feature or report a bug?

"Feature" - as in, improve docs

What is the current behavior?

If the current behavior is a bug, please provide the steps to reproduce.

When creating a Windows installer on Windows I found I was missing a number of requirements, none of which is mentioned in the docs at https://oclif.io/docs/releasing:

oclif pack win requires:

1. 7z --> 7Zip needs to be in the PATH
2. makensis --> had to install NSIS and add it to the PATH
3. grep --> got around this one by running on a git bash. Library recommendation would be useful

What is the expected behavior?

Please can you update the docs with installation prerequisites. The current docs are misleading because they make it look like the pack command works out of the box.

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please delete the greenkeeper/initial branch in this repository, and then remove and re-add this repository to the Greenkeeper App’s white list on Github. You'll find this list on your repo or organization’s settings page, under Installed GitHub Apps.

Can we create platform executables with oclif?

I have created a sample cli using oclif. Now I want to create .exe, .dbg executables. Is it possible to create these using oclif, if yes is there any sample I can refer?

More Details Documentation for Release

Documentation is outdated with oclif's v2 and above

I've tried to follow site documentation, and on the very first pages noticed it wasn't working. I even opened a PR to update Generator Commands (#133), but seems like every page is outdated and don't properly guide/explain oclif's version 2 and above.

Page not found

Describe the bug
The next button at "Running Commands Programmatically" under the "How to" next button leads to a 404 page.
it is supposedly meant to link to . same with the previous button on Aliases section.

To Reproduce
Steps to reproduce the behavior:

1. Go to Running Prorammatically page
2. Click on the next at the bottom of the page
3. See error

Expected behavior
Direct to the Aliases page

Screenshots
If applicable, add screenshots to help explain your problem.

Environment (please complete the following information):

• OS & version: MacOS Monterey 12.6.2
• Browser: Google Chrome Version 111.0.5563.110 (Official Build) (x86_64)