github.com/circl-dev/go-swagger@v0.31.0/examples/cli/README.md (about)

     1  # Generate CLI Client Tool
     2  Generate a command line client tool for your server
     3  (This is in alpha state and is under development)
     4  
     5  * Generated CLI code is a wrapper of the generated client code, which reads command line options and args to construct appropriate parameters and send to the server.
     6  * Based on [cobra framework](https://github.com/spf13/cobra), and [viper](https://github.com/spf13/viper).
     7  * Support shell completions.
     8  * For advanced example, see [dockerctl](https://github.com/go-swagger/dockerctl), a CLI generated using this for [docker engine](https://www.docker.com/)
     9  ## General Command Layout
    10  * Root command manages global flags
    11  * Each open-api tag is a sub-command under root command. In go-swagger it is called operation group.
    12  * Each open-api operationId is a sub-command under the tag it belongs to.
    13      * Each path and query parameter is a command line flag.
    14      * Body parameter corresponds to a command line flag, as a json string.
    15      * Each field in body parameter is a command line flag, and this extends to sub-definitions recursively.
    16          * body parameter json string will be taken as base payload, which flags for body fields will overwrite.
    17  
    18  # Todo List CLI App Example
    19  CLI tool in this folder is generated using the same swagger.yaml as `examples/auto-configure`. We will run that server to test this cli executable.
    20  
    21  ## Getting Started
    22  ### Generate the code (optional)
    23  Generate go-swagger command (optional for this example, since code is already generated and checked-in in repo):
    24  ```
    25  $ swagger generate cli --target=examples/cli --spec=examples/cli/swagger.yml --cli-app-name todoctl
    26  ```
    27  ### Run the CLI program
    28  #### Run the tool using go run
    29  ```
    30  $ go run examples/cli/cmd/todoctl/main.go --debug --hostname localhost:12345 --x-todolist-token "example token" todos addOne --item.description "hi" --body "{}"
    31  ```
    32  #### Build the executable and then run
    33  ```
    34  $ go build -o examples/cli/cmd/todoctl/todoctl examples/cli/cmd/todoctl/main.go
    35  $ ./examples/cli/cmd/todoctl/todoctl
    36  ```
    37  ### Shell Completion
    38  Shell completion is supported via [cobra](https://github.com/spf13/cobra#generating-shell-completions). bash, zsh, fish, PowerShell completion script can be generated by the CLI executable. More technical details [here](https://github.com/spf13/cobra/blob/master/shell_completions.md).
    39  For example, bash completion is generated like this to stdout:
    40  ```
    41  $ ./examples/cli/cmd/todoctl/todo-cli completion bash
    42  ```
    43  To use the completion, do the following:
    44  ```bash
    45  # temporary completion in current shell
    46  $ source <(./examples/cli/cmd/todoctl/todoctl completion bash)
    47  # add completion permanently to your system
    48  $ ./examples/cli/cmd/todoctl/todoctl completion bash > /etc/bash_completion.d/todoctl
    49  ```
    50  ### Help Message Example
    51  * Help messages can be obtained as follows:
    52  ```bash
    53  $ ./examples/cli/cmd/todoctl/todoctl --help
    54  ```
    55  ```bash
    56  $ ./examples/cli/cmd/todoctl/todoctl todos updateOne --help
    57  ```
    58  ### Use config file to store common flag values
    59  `hostname`, `scheme`, and auth tokens can be read from a config file, so that you do not need to enter it every time via command line.
    60  For example, todo-cli config file looks like this:
    61  ```json
    62  {
    63      "hostname":"localhost:12345",
    64      "scheme":"http",
    65      "x-todolist-token":"example token"
    66  }
    67  ```
    68  The default location that the CLI will look for config file is `~/.config/<program name>/config.json`. One can also specify a config file location via flag`--config`. One can use `yaml`,`env`, etc file types, and the CLI can parse them all. The config file is supported via [viper](https://github.com/spf13/viper).
    69  With the above config file for todo-cli, one can invoke the command like this:
    70  ```bash
    71  $ ./examples/cli/cmd/cli/todo-cli todos findTodos
    72  ```
    73  ## Exercise: Running CLI against auto-configure server
    74  * Start the server
    75  ```
    76  $ go run examples/auto-configure/cmd/a-to-do-list-application-server/main.go --port=12345
    77  ```
    78  * Make request using the CLI tool (using another shell)
    79  ```
    80  $ go run examples/cli/cmd/todoctl/main.go --hostname localhost:12345 --x-todolist-token "example token" todos addOne --item.description "hi" --body "{}"
    81  {"description":"hi"}
    82  
    83  $ go run examples/cli/cmd/todoctl/main.go --hostname localhost:12345 --x-todolist-token "example token" todos findTodos
    84  [{"description":"hi"}]
    85  
    86  $ go run examples/cli/cmd/todoctl/main.go --hostname localhost:12345 --x-todolist-token "example token" todos updateOne --id 1 --item.completed true --item.description "done"
    87  {"code":404,"message":"Item with id 1 is not found"}
    88  ```
    89  
    90  ### Missing Features
    91  * Array and maps in body (It is unclear how to support)
    92  * Enums
    93      * In help message
    94      * In shell auto-complete
    95  * Validate params before sending