Create your command line tool

warning

The CLI generator is currently experimental, which means that we may make some breaking changes to improve the quality of the tools that are generated.

This guide will describe how you can generate a command line tool that can be used to interact with your API backend and how it will work. You can use this tool with shell scripting or from inside other programs that can invoke shell commands.

Considerations

The CLI generator creates a wrapper around your Go SDK with command line argument parsing. Thus, Go must be included as one of your SDK targets, and you must have a public-facing repository for your Go SDK.

Command line interfaces have some limitations that make it awkward to pass deeply nested structures as command line arguments. The command line interface generator will do its best to make the command line tool's flags as ergonomic as possible, but you may have to provide deeply nested parameters in JSON format in some cases.

Build process

Make sure you have Go as a target for SDK generation and that you have linked a production repository for your Go SDK.

Once you have a production Go repository, you can create a new CLI target in your Stainless dashboard. After adding a CLI target, save and build your current branch.

note

If you do not have a production repository for Go, the build process will fail on the "Lint" phase with the following error: Error: retrieve-github-access-token failed: https://api.stainlessapi.com/api/github-access-token received 401 Unauthorized

The build process will create a new repository for your CLI tool. Your CLI tool's binary name will be taken from the targets.cli.binary_name field in your Stainless config. You can also optionally specify which Go SDK package and version you want to use.

targets:
  go:
    ...
  cli:
    binary_name: your-project
    options:
      go_sdk_package: ...
      go_sdk_version: ...

To test and debug your CLI tool before release, clone your CLI repo and run the tool with Go as documented in the repo's README.md.

Release your CLI tool

When you're satisfied with your CLI tool, release it by following the steps to publish your SDK as you would with any other SDK target. Your published CLI tool will include man pages. When running locally, you can generate your man pages by running your-tool @manpages.

Usage

The basic structure of your command line tool follows this format:

your-tool [resource [sub-resource...]] method-name --method-arg value

For example, if your Stainless configuration had the following configuration:

resources:
  $client:
    methods:
      current_status: get /status
  people:
    methods:
      retrieve: get /person
      create: post /person
      list: get /people

Then your generated CLI tool could be used like this:

my-tool current-status

# Output: {"status": "Up and running!"}

my-tool people create --job "President" \
    --name.full-name "Abraham Lincoln" \
    --name.nickname "Abe Lincoln"

# Output: {
#   "created": {
#     "id": 123,
#     "name": {
#       "full_name": "Abraham Lincoln",
#       "nickname": "Abe Lincoln"
#     },
#     "job": "President"
#   }
# }

my-tool people retrieve --id 123

# Output: {
#   "id": 123,
#   "name": {
#     "full_name": "Abraham Lincoln",
#     "nickname": "Abe Lincoln"
#   },
#   "job": "President"
# }

my-tool people list

# Output: {
#   "people": [
#     {
#       "name": {
#       "full_name": "Abraham Lincoln",
#       "nickname": "Abe Lincoln"
#     },
#     "job": "President"
#   }
# ]

Note that method names like current-status and flags like --first-name use kebab-case, which is conventional for command line tools.

Argument parsing

Full argument parsing documentation for your command line tool can be found using the --help flag:

# General help
my-tool --help

# Help for a specific endpoint
my-tool people create --help

In addition to specifying values by command line flags, you can also pipe JSON data into the tool:

my-tool people create <<END
{
  "name":{"full_name": "Abraham Lincoln", "nickname": "Abe Lincoln"},
  "job": "President"
}
END

# Output: {
#   "created": {
#     "id": 123,
#     "name": {
#       "full_name": "Abraham Lincoln",
#       "nickname": "Abe Lincoln"
#     },
#     "job": "President"
#   }
# }

Top-level flags

There are a small number of top-level flags:

• --help, -h: show a help message and exit.
• --version, -v: print the CLI tool's version and exit.
• --base-url: provide a base URL for the API backend.
• --format=...: change the output formatting (see below).

Output formatting

The default output format for CLI commands is formatted and syntax-highlighted JSON. You can select different output formats using the --format flag:

• --format=auto: output format is automatically chosen, currently this defaults to json, but may change in the future.
• --format=json: JSON output with autoformatting and syntax highlighting (or without syntax highlighting when used in a pipe or when the FORCE_COLOR=0 environment variable is set).
• --format=raw: the exact raw JSON response sent from the server (no formatting or coloring applied).
• --format=yaml: the response in YAML format.
• --format=pretty: a nice-looking human-readable format similar to YAML with a box around it.
• --format=explore: an interactive TUI explorer that lets you browse through nested data.

Next Steps

If you find a bug, have a question, or want to provide product feedback, let us know at support@stainless.com.