CLI Generation

The CLI will be behind a crate feature flag cli which is turned off by default. To build the CLI binary from your generated Rust codebase run:

# Run from the root of the generated Rust codebase
cargo build --features cli --release
 
# The built CLI executable will be written to ./target/release/<CLI_NAME>
# if the CLI name was `my-cli` the following will print the top-level
# help message to the console
./target/release/my-cli --help

By default cargo will build the executable suitable for the current OS/architecture. If you would like to build for additional targets see the cargo build documentation.

If you wish to play around with the CLI without building simply run cargo run --features cli -- <COMMAND> which will automatically compile the code and run the given command.

All Sideko generated CLIs come with a stadard config subcommand group. This subcommand group contains useful utilities for authenticating, documenting, and further configuring the CLI once it is installed. To see a full list of the available configuration commands in your CLI run:

my-cli config --help

Each generated CLI can output a Markdown file listing all of it's commands, arguments, etc. including usage examples with example values sourced from OpenAPI:

# Will output ./CLI.md
my-cli config docs

Each generated CLI comes with auto-completion functionality for a veriaty of supported shells (bash, elvish, fish, powershell, and zsh). The output of this command can be piped to a file that is sourced automatically when your shell initializes for the best user experience. e.g.

my-cli config completions --shell zsh > completions.sh && source completions.sh
 
# Now  my-cli + [TAB]  will display a number of auto-completed options

All generated CLIs will include an optional -v or -vv flags for different levels of verbosity in the output. This is useful for debugging API errors that may occur, for example the CLI was used to hit an authenticated endpoint with invalid credentials, or the JSON returned by the server does not match the schema listed in the OpenAPI causing a failure during deserialization.

Like all of our generated SDKs, the generated Rust CLI is able to handle many different authentication methods as described in OpenAPI. For each authentication method listed, a command will be generated in the config auth command group. The inputs for these commands will vary according to the authentication method listed (basic/bearer/key/oauth). Running these authenication commands will cause the inputted credentials to be stored in the CLI's configuration file. By default the location of this configuration file is saved to $HOME/.sideko-cli but this can be cusomized by setting the SIDEKO_CLI_CONFIG environment variable.

You can optionally configuer an oauth2 authentication method using the x-sideko-oauth field such that the generated config auth [OAUTH_COMMAND] command dynamically hists a given endpoint and save the access token it returns.

For example given the following OpenAPI:

paths:
  /token:
    post:
      operationId: create_token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Login'
      responses:
        '200':
          description: Token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
  /items:
    get:
      operationId: list_items
      security:
        - oauth:
            - 'read:items'
      responses:
        '200':
          description: Items retrieved
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    Login:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
        password:
          type: string
    Token:
      type: object
      required:
        - access_token
        - token_type
      properties:
        access_token:
          type: string
        token_type:
          type: string
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        password:
          tokenUrl: token
          scopes:
            'read:items': read your items
            'write:items': modify your items
      x-sideko-oauth:
        operationId: create_token
        tokenJsonPointer: /access_token
 

To summarize:

1. The /token POST endpoint accepts a body with username and password fields returning a JSON object with the access_token upon successful verification of the given credentials.
2. The /items GET endpoint requires authentication via the oauth security scheme and returns a list of items from the API.
3. The oauth security scheme contains the x-sideko-oauth field configuring the CLI to hit the endpoint with operationId create_token to retrieve the token. Additionaly it lists a json pointer pattern that the CLI can use to extract the relevant field from the json response and save it to the CLI configuration file to be used by future requests. You can read more about json pointers and their syntax here

If the generated CLI was called my-cli then the process of authenticating it and listing the items is:

my-cli auth oauth --username johndoe --password supersecret
my-cli items list

Each endpoint listed in the OpenAPI specification will have a CLI command generated for it organized automatically into command groups. See SDK Customizations for more details on how to override the default groups (x-sideko-module) and command names (x-sideko-function-name). Command parameter requirements and types will be determined by the data in the OpenAPI specification.