CLI

When you install the peak-sdk, you get an awesome CLI bundled with it. Using the CLI you can perform any action that you can with the SDK. The CLI is available with the peak command.

Getting Help

  • To get help about how to use the CLI, and the commands available just pass in the --help option to the command

    peak --help
    
  • You can refer to the Reference Doc and the Usage Doc to get more details about each of the available commands.

Enable Auto-completion

  • To enable auto-completion for your shell run the following command, where shell can be one of [bash|zsh|fish|powershell|pwsh].

    peak --install-completion ${shell-name}
    
  • Once this has run, we need to add compinit to the shell configuration file (like - .zshrc, .bashrc, etc). To do so, you can the following command

    echo "compinit" >> ~/.zshrc # replace .zshrc with your shell's configuration file
    

Dry Run

  • At times, you might just want to check out what the CLI does when you run a particular command - what API call it makes, what data it passes to the API, etc without actually calling the API.

  • You can achieve this by passing the --dry-run option to the respective command.

    • Remember that --dry-run is not available in commands that just describes or lists the data.

  • For example, if you want to check what all data is passed to the Image creation API when you create an image, run the following command

    peak images create image-config.yml --dry-run
    

    This generates the following output

    Sample request: {
      "url": "https://service.peak.ai/image-management/api/v2/images/",
      "method": "POST",
      "headers": {
        "x-peak-sdkVersion": "1.10.0",
        "x-peak-os": "macOS-13.5.2-arm64-arm-64bit",
        "x-peak-hostname": "hostname",
        "x-peak-pythonVersion": "3.11.4",
        "x-peak-sessionId": "df80cff3-cba6-4e7d-bfb0-f0c317c2bcc5",
        "x-peak-requestId": "0492a3e4-744b-4f73-9cae-174c4a37004e",
        "Authorization": "<API KEY>",
        "User-Agent": "peak/1.10.0 CPython/3.11.4 Darwin/22.6.0"
      },
      "params": {},
      "body": {
        "version": "0.0.2-awesome",
        "type": "workflow",
        "name": "123"
      }
    }
    
    
    Artifact file tree:
    Dockerfile
    hello
    ├── world
    |   ├── 3.txt
    ├── 2.txt
    ├── 1.txt
    
  • --dry-run is not available in create_or_update functions in any of the resources.

Paging

  • The CLI contains a lot of commands that allows you to get a list of resources, or all the details about a specific resource. The output for these commands can be quite big and can overflow your terminal window.

  • At times, you might want to use a pager to be able to easily view the complete data, paging through the data line by line as needed. Don’t fret, the CLI has an option for this as well.

  • To enable paging, just pass in --paging to the command. It will use the default pager for your terminal to display you the output.

  • For example, if you want to view the list of images in a paged format just run the following command

    peak images list --paging
    

Output Format

  • Whenever you run a CLI command, you have the option to choose the format in which you want to see the data. Three formats are supported -

    • json

      • This is the default output format. The JSON response from the APIs is directly displayed.

        peak images list
        
    • yaml

      • This displays the data in the YAML format. This can be very helpful when describing a resource as you can then very easily using the response in update or other APIs.

        peak images list --output=yaml
        
    • table

      • For all the List APIs, you have the option to view the data in a tabular format.

      • Remember that not all the data returned by the API is displayed in the table, and only a few important keys are displayed.

        peak images list --output=table
        
  • You can use either --output or -o to specify the output format

    peak images list --output=table
    peak images list -o table
    

Generate YAML Config

  • The CLI allows you to generate a YAML config file for any resource. This can be very helpful when you want to create a resource using the CLI, but don’t want to write the YAML config file yourself.

  • To generate a YAML config file for a resource, you can run the following command specifying the resource and operation you want to perform

    peak images create --generate
    
  • This will generate a YAML config file for the resource and operation you specified and display it on the terminal. You can then copy this config file and use it to create the resource.