From 132f65c5908127315ca277c1af111356709d53b4 Mon Sep 17 00:00:00 2001 From: Aaron Fischer Date: Wed, 8 Nov 2023 10:12:18 +0100 Subject: [PATCH] Add a comprehensive README --- README.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 61 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index f4e6011..c21859d 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,63 @@ # GPORTAL Cloud CLI -A handy little commandline tool to access the GPORTAL Cloud API. +Commandline tool to access the GPORTAL Cloud API. ## Install and update +Download the latest binary from the release page, make it executable and run it. +To update the CLI, just run the ```selfupdate``` command. It will download the +latest release from GitHub and replace the current binary. + +## Overview + +The commandline tool works in two different modes: As a server and as a client. +The server is a standard ssh server, which does the heavy lifting. The server +logs into the GPORTAL Cloud API once and wait for commands from the client. + +The server acts as a proxy between the client and the API. The client connects +to the server and sends commands to it. The server executes the commands and +returns the result to the client. With this architecture, the client does not +open up a new connection for every command, which saves time and resources. + On first run, it asks for credentials (client-id, client-secret, username and -password) and saves them in a config file or the system keyring. To update -the CLI, just run the ```selfupdate``` command. It will download the latest release -from GitHub and replace the current binary. +password). Non-critical information will be stored in a config file +( ~/.config/gportal/config.json ). Sensitive information will be stored in the +keyring (if supported by the OS). The keyring is encrypted with the user's +password. To secure the connection between client and server, a SSH public/private +key pair will be generated and secured with a passphrase. The passphrase is +the same as the password for the GPCloud account. This way, the connection +between client and server is secured and no other ssh client can connect to it. + +If you messed up your config, the sensitive data in the keyring or the piblic/private +key, you can reset everything with the ```reset-config``` command. + +The agent (SSH server) will start automatically and place it in the background, +until the user actively stops it with ```agent stop```. So the first command will +take a little longer (because the agent has to start), but all following commands +will be executed immediately. +The client itself is a simple SSH client. It connects to the agent and sends +commands to it. The result is printed to stdout. You can use the standard +SSH command (ssh) to connect through it, but it is not that convenient. + +## Usage + +The commandline tool is separated into subcommands. To get a list of all +available subcommands, run ```gportal help```. To get help for a specific +subcommand, run ```gportal help ```. + +As and example, to list all projects, run ```gportal project list```. If you run +just the subcommand without any arguments, you will get a list of all available +actions for that subcommand. + +Some commands need flags or specific parameters. To get a list of all flags and +parameters, run ```gportal help ```. For example, to change +the active project, run ```gportal project set-active --id ```. + +By default, the output is formatted as a ASCII table. If you want to pass the +output to other tools for processing, you can append the flag ```--csv``` or +```--json```. For example: ```gpcloud project list --json | jq 'length``` ## Development @@ -19,18 +67,19 @@ add a new subcommand, see ```pkg/generator/definition/``` for some examples. Generated code files are NOT checked in, because the user can always generate them himself. This is done to avoid merge conflicts. - You can always add custom subcommands without generating it. Just add a new file to ```cmd/```. The file name will be the name of the subcommand. +With hooks, you can inject code at some points in auto generated code. For +example, if you want to remove some colums, format certain colums or validate +input, you can do this with hooks. Create a file in the same package with the +same name of the action (auto generated file), but with the prefix ```_pre.go``` +to execute code before the action and ```_post.go``` to execute code after the +action but before the outout is printed. As an example, see ```project/list_post.go```. -## TODO after release -* Check selfupdate -* Fix interactive command -* Write a comprehensive README for developers -### Nice to haves +### Ongoing tasks -* Migrate code generation to Jennifer +* Migrate code generation to Jennifer for more advanced stuff (pagination) * Pagination support for long lists (pending because of Jennifer migration) -* Separate admin and non admin commands (or check if the user is an admin?) +* Complete the API endpoints, so everything is accessible through the CLI tool