Commandline tool to access the GPCORE API.
Download the latest binary from the release page, make it executable and run it.
To update the CLI, just run the gpcore selfupdate command. It will download the
latest release from GitHub and replace the current binary.
To use shell completion for the gpcore command, you can generate the completion
script with the gpcore completion command. Supported shells are bash, zsh
fish and PowerShell. It will print the script to stdout, so pipe it in a file
and source it in your shell.
gpcore completion bash > /etc/bash_completion.d/gpcore
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 GPCORE 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 the first run, it asks for credentials (client-id, client-secret, username and 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, an SSH public/private key pair will be generated and secured with a passphrase. The passphrase is the same as the password for the GPCORE 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 public/private
key, you can reset everything with the gpcore agent setup command.
The GPCORE API has a concept of admin permissions. Several actions can only
be executed with admin permissions. Use the --admin flag on the agent
setup to set the admin credentials as well. Use your normal GPCORE account
credentials for that. The admin credentials will be stored in the keyring
and used to execute admin actions.
NOTE: The tool does not support 2FA at the moment, so you have to disable it for your GPCORE account to use the CLI. You still can use Passkey.
To make sure that you have admin permissions, you can use the user details
command, which will show the admin flag. You also see more actions with
the help command, if you have admin permissions. If you have the admin
flag but get an unauthorized error, you probably have to set the super-admin
role on your service account in Keycloak. Ask a GPCORE administrator for help.
If you logged in as a normal user and want to switch to admin mode, you first
need to stop the agent with gpcore agent stop, then run the agent setup
again with gpcore agent setup --admin.
The agent (SSH server) will start automatically and place itself in the background,
until the user actively stops it with gpcore 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. If you want to see the output of the agent,
you can run the agent in the foreground with gpcore agent start in a separate
terminal.
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.
The commandline tool is separated into subcommands. To get a list of all
available subcommands, run gpcore help. To get help for a specific
subcommand, run gpcore help <subcommand>.
As and example, to list all projects, run gpcore 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 gpcore help <subcommand> <action>.
A lot of commands need a project ID to work with. To make the commandline tool
more convenient, you can set the active project with the
gpcore project use --id <project-uuid> command. This will set the active
project for all commands which need a project 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: gpcore project list --json | jq 'length
All files which ends with _gen.go are autogenerated and should not be
edited manually. To regenerate them, run go generate. If you want to
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 output is printed. As an example, see project/list_post.go.
To increase the log level verbosity, you can set it with the loglevel
command (gpcore loglevel debug).