Designing a Human-Friendly CLI for API-Driven Infrastructure
- 30 minutes
As Bloomberg’s infrastructure grows and evolves, the tools we use to manage it are becoming increasingly important. To streamline infrastructure management, our team set out to design a REST API and constituent CLI (Command Line Interface) that would comprise a single interface for both programmatic and human interaction with our infrastructure. Traditionally, building a CLI that is tightly coupled to an API requires maintaining a separate codebase, which is tedious and error-prone. Instead, we designed a CLI that dynamically generates commands based on the OpenAPI JSON documentation. However, since APIs are designed for computer interaction, we designed our API to include the information needed to implement a human-friendly CLI. Leveraging Python, FastAPI, and numerous other open source projects, we built a stable, extensible tool that greatly improves how we interact with our infrastructure.
In this talk, we will share our experience designing a resilient infrastructure API with a human-friendly CLI that does not need continued development, even as the API evolves.
We will discuss some of the specific approaches we used to build a dynamically-updated CLI with human-friendly features:
- Extending OpenAPI to communicate CLI intent
- Using templating languages (Jinja) to convert the API’s response JSON into human readable output
- Defining CLI command aliases to abstract long, verbose API endpoints
- Embedding CLI help text in the API to generate well-documented commands
- Other small enhancements and strategies that improve the CLI user’s quality-of-life.
Furthermore, we will also discuss how we leveraged several open source projects and standards to accomplish our goals, including Python, FastAPI, OpenAPI, Jinja, OAuth2, Pydantic, prompt_toolkit, and more.