This is a framework for building CLIs in Node.js. This framework was built out of the Salesforce CLI but generalized to build any custom CLI. It's designed both for single-file CLIs with a few flag options (like cat
or ls
), or for very complex CLIs that have subcommands (like git
or heroku
).
See the docs for more information.
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.
--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 hello-world CLI examplets-node
to run the plugins enabling you to use TypeScript with minimal-to-no boilerplate needed for any oclif CLI.$ heroku info --app=<tab><tab> # will complete with all the Heroku apps a user has in their account
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.
See the v3 migration guide for an overview of breaking changes that occurred between v2 and v3.
See the v2 migration guide for an overview of breaking changes that occurred between v1 and v2.
Migrating from @oclif/config
and @oclif/command
? See the v1 migration guide.
The official oclif website, oclif.io, contains all the documentation you need for developing a CLI with oclif.
If there's anything you'd like to see in the documentation, please submit an issue on the oclif.github.io repo.
We strongly encourage you generate an oclif CLI using the oclif cli. The generator will generate an npm package with @oclif/core
as a dependency.
You can, however, use @oclif/core
in a standalone script like this:
#!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning
import * as fs from 'fs'
import {Command, Flags, flush, handle} from '@oclif/core'
class LS extends Command {
static description = 'List the files in a directory.'
static flags = {
version: Flags.version(),
help: Flags.help(),
dir: Flags.string({
char: 'd',
default: process.cwd(),
}),
}
async run() {
const {flags} = await this.parse(LS)
const files = fs.readdirSync(flags.dir)
for (const f of files) {
this.log(f)
}
}
}
LS.run().then(
async () => {
await flush()
},
async (err) => {
await handle(err)
},
)
Then run it like this:
$ ts-node myscript.ts
...files in current dir...
You can also use oclif's Parser
separately:
// index.js
import {Args, Flags, Parser} from '@oclif/core'
const {args, flags} = await Parser.parse(process.argv.slice(2), {
args: {
name: Args.string({required: true}),
},
flags: {
from: Flags.string({char: 'f', default: 'oclif'}),
},
})
console.log(`hello ${args.name} from ${flags.form}`)
$ node index.js world --from oclif
hello world from oclif
🚀 Contributing
See the contributing guide.