oclif / hello-world

Template repository for generating CJS oclif plugins

oclif CLI

• oclif CLI
• 🗒 Description
• 🚀 Getting Started Tutorial
• 📌 Requirements
• 📌 Migrating from V1
• 🏗 Usage
• 📚 Examples
• 🔨 Commands
• Command Topics
• 🚀 Contributing
• 🏭 Related Repositories
• 🦔 Learn More

🗒 Description

This is the oclif CLI for the Open CLI Framework, that supports the development of oclif plugins and CLIs.

See the docs for more information.

🚀 Getting Started Tutorial

The Getting Started tutorial is a step-by-step guide to introduce you to oclif. If you have not developed anything in a command line before, this tutorial is a great place to get started.

See Usage below for an overview of the oclif CLI.

📌 Requirements

Currently, Node 18+ is supported. We support the LTS versions of Node. You can add the node package to your CLI to ensure users are running a specific version of Node.

📌 Migrating from V1

If you have been using version 1 of the oclif CLI there are some important differences to note when using the latest version.

Breaking Changes

• oclif multi, oclif plugin, and oclif single have all been removed in favor of oclif generate, which generates an oclif based CLI using the hello-world example repo.
  • The reason is that there's not enough of a meaningful difference between a "multi command cli", a "single command cli", and a "plugin" to justify the maintenance cost. The generated CLI can be easily used for any of those use cases.
• oclif hook is now oclif generate:hook
• oclif command is now oclif generate:command

New Commands

Version 2 now includes all the commands from the oclif-dev CLI. This means that you can now use a single CLI for all your oclif needs. These commands include:

• oclif manifest
• oclif pack
• oclif pack:deb
• oclif pack:macos
• oclif pack:win
• oclif upload (formerly known as oclif-dev publish)
• oclif upload:deb (formerly known as oclif-dev publish:deb)
• oclif upload:macos (formerly known as oclif-dev publish:macos)
• oclif upload:win (formerly known as oclif-dev publish:win)
• oclif readme

🏗 Usage

Creating a CLI:

$ npx oclif generate mynewcli
? npm package name (mynewcli): mynewcli
$ cd mynewcli
$ ./bin/run.js --version
mynewcli/0.0.0 darwin-x64 node-v9.5.0
$ ./bin/run.js --help
USAGE
  $ mynewcli [COMMAND]

COMMANDS
  hello
  help   display help for mynewcli

$ ./bin/run.js hello world
hello world! (./src/commands/hello/world.ts)

📚 Examples

• Hello-World
• Salesforce CLI
• Heroku CLI

🔨 Commands

Command Topics

• oclif generate - Generate a new CLI
• oclif help - Display help for oclif.
• oclif init - Initialize a new oclif CLI
• oclif manifest - Generates plugin manifest json (oclif.manifest.json).
• oclif pack - Package an oclif CLI into installable artifacts.
• oclif promote - Promote CLI builds to a S3 release channel.
• oclif readme - Adds commands to README.md in current directory.
• oclif upload - Upload installable CLI artifacts to AWS S3.

🚀 Contributing

See the contributing guide.

🏭 Related Repositories

• @oclif/core - Base library for oclif. This can be used directly without the generator.
• @oclif/test - Test helper for oclif.

🦔 Learn More

• Salesforce Release Announcement
• Heroku Release Announcement

hello-world's Issues

Make ESM friendly template

Current template is specifically for CJS and requires modifications by the user to convert it to ESM. There are issues even after following the docs, like the tests don't pass.

We need to add a template that supports ESM without any modifications by the user and with tests that pass

The new template should be accessible through oclif's generator

build script throws TypeScript errors in environments with jest

I've generated a CLI inside my mono-repository, and it seems like @types/mocha type declarations conflict with jest ones I use in another package. It only happens because of my environment, but it could be avoided by using the skipLibCheck option in tsconfig.json.

skipLibCheck also saves compilation time by skipping type checking dependencies.

../../../node_modules/@types/mocha/index.d.ts(2642,13): error TS2403: Subsequent variable declarations must have the same type.  Variable 'beforeEach' must be of type 'Lifecycle', but here has type 'HookFunction'.
../../../node_modules/@types/mocha/index.d.ts(2660,13): error TS2403: Subsequent variable declarations must have the same type.  Variable 'afterEach' must be of type 'Lifecycle', but here has type 'HookFunction'.
../../../node_modules/@types/mocha/index.d.ts(2676,13): error TS2403: Subsequent variable declarations must have the same type.  Variable 'describe' must be of type 'Describe', but here has type 'SuiteFunction'.
../../../node_modules/@types/mocha/index.d.ts(2697,13): error TS2403: Subsequent variable declarations must have the same type.  Variable 'xdescribe' must be of type 'Describe', but here has type 'PendingSuiteFunction'.
../../../node_modules/@types/mocha/index.d.ts(2711,13): error TS2403: Subsequent variable declarations must have the same type.  Variable 'it' must be of type 'It', but here has type 'TestFunction'.
../../../node_modules/@types/mocha/index.d.ts(2725,13): error TS2403: Subsequent variable declarations must have the same type.  Variable 'test' must be of type 'It', but here has type 'TestFunction'.
../../../node_modules/@types/mocha/index.d.ts(2732,13): error TS2403: Subsequent variable declarations must have the same type.  Variable 'xit' must be of type 'It', but here has type 'PendingTestFunction'.
../../../node_modules/@types/sass-loader/interfaces.d.ts(410,43): error TS2314: Generic type 'Options<sync>' requires 1 type argument(s).

VSCode warns about using referenced projects without been composite

Every time a open the CLI package the VSCode warns me about an incorrect tsconfig.json that uses project references without having composite enabled. After looking at the docs I've confirmed that VSCode is right.

Link of TS's project references docs:
https://www.typescriptlang.org/docs/handbook/project-references.html#composite

Since tests/tsconfig.json is only used by test runner we don't see any error in the console, but for long term this may cause some troube.

Error: command hello:world not found

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

This is a bug.

What is the current behavior?

Command ./bin/run hello:world not working.

Steps to reproduce -

Commands fired -

$ oclif generate stream
$ ./bin/run hello:world
Error: command hello:world not found

generate command pulls oclif/hello-world repo as a template.

What is the expected behavior?

hello world! (./src/commands/hello/world.ts)

versions-
oclif: 2.1.0
oclif/core: 1.1.0
OS: OSX 11.5.2
Node: 14.17.1

Debugging in vscode not working with hello-world

I did the following:

1. checkout of hello-world
2. npm install
3. npm run build
4. /bin/run to verify everything

So far works fine.

Now I added launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "skipFiles": [
                "<node_internals>/**"
            ],
            "program": "${workspaceFolder}\\bin\\run",
            "args": [
              "hello",
              "world",
            ],
        }
    ]
}

and set a breakpoint in world.ts:17 (run()).
The debugger never hits the breakpoint in the TS file.

How can I debug oclif projects in vs code?

Remove unused code and dependencies

Some part of the template seems to be useless:

• devDependencies tslib is not referenced by any files

• The cli seems to work without src/index.ts