Today we're excited to announce that we've open sourced oclif, a framework for building command line interfaces.
We built oclif to serve as the common foundation for both the Heroku and Salesforce CLIs and to abstract away the common struggles. The framework is now available to any developer for building CLIs large or small. oclif makes building CLIs more accessible by providing you with the patterns and tools to scaffold a working command line interface. It provides a structure for simple to advanced CLIs, including documentation, testing, and plugins for adding new commands.
With oclif you can get up and running with your command line interface quickly, and focus on the implementation of the commands themselves.
oclif is a Foundation for Your CLI
oclif distills our expertise from years of building and maintaining CLIs used by millions of developers. It provides the performance that large codebases require and the simplicity that makes it easy to build small CLI's. Features include:
- CLI Generator — Quickly scaffold out a new CLI and new commands
- Documentation — In-CLI documentation with
--helpand markdown documentation is automatically generated - Plugins — Allow CLI users to extend your CLI with new functionality
- And more
Why Build a CLI?
A well-designed command line gives its users power and productivity. There are lots of use cases where you might want to build a command line interface:
- To provide a simple interface for users to interact with your API
- As a platform to share commonly-used scripts at your company
- To prototype a feature quickly without needing to build a web interface
- To perform bulk tasks, such as adding a large number of users or details to an account
Designed for Delightful CLI Experiences
We believe CLIs should be designed primarily for human readability and usability, while at the same time supporting advanced users and output formats. For example, input and output should be consistent across commands to allow the user to easily learn how to interact with new commands. oclif follows the usability principles in our CLI Style Guide, which provides direction on designing a delightful CLI experience.
Getting Started
Creating a Single CLI (with just one command) can be done in less than 3 minutes! The requirements are Node, npm and yarn. Try our getting started tutorial to get up and running right away.
oclif Example Project: kaomoji
The Heroku and Salesforce CLI projects are large and complex, so we built a small example CLI from the ground up to test out oclif and give you an idea of what is possible with oclif on a smaller scale. Hello kaomoji!
Have you ever struggled to find the appropriate emoji for your conversation? In this example we'll create a CLI, built on oclif, that enables you to search for an ASCII kaomoji (Japanese style emoticons) in your command line interface. To get started
- Generate scaffold - run
npx oclif single <your cli name, e.g. kaomoji>, 'single' here denotes a single-command CLI. Read more about what that means in the oclif docs. - Add metadata - answer the questions to describe your CLI and where it lives in GitHub
- Hello world! - your scaffold is up and running
- Customize - edit the generated
index.tsTypeScript class to add your CLI logic, e.g. search a kaomoji dictionary based on a keyword and return the kaomoji (note: you don't have to use TypeScript, but it's encouraged) - It's working - run
./bin/runto test your CLI ᕕ( ᐛ )ᕗ
Learn More
You can learn more about oclif on its dedicated community site, which includes detailed documentation, example projects, and links to sample code. We also discuss the development of oclif in more depth in the Salesforce engineering blog.
We'd love to hear your feedback as you develop on oclif and welcome your contributions. We even have a few Github issues that would be great for first-time contributors. We'd also love to include more examples of CLI's built with oclif on our site. Please drop us a line at ecosystem-feedback@heroku.com or join the conversation in Gitter.