RESTish CLI
Why Use RESTish?
Currently, we don’t have a comprehensive CLI tool for interacting with Katapult, but we do have a fully functional REST API that you can use to interact with Katapult today.
What is RESTish?
RESTish is a CLI for interacting with RESTish HTTP APIs. It has built-in features, like always having the latest API resources, fields, and operations without needing to install or update anything. We think it works great with Katapult.
You can find the GitHub page for RESTish here
OpenAPI Specification
We offer an OpenAPI specification that allows you to generate client libraries for your preferred programming language. You can also use restish, a tool we recommend as a temporary alternative to a CLI.
Our OpenAPI specifications are available here:
Set up RESTish
Install RESTish
Follow the install and setup instructions here.
Configure RESTish for Katapult
This setup will allow you to access and manage Katapult’s Core API endpoints directly from the command line,
streamlining your workflow and enabling efficient API operations.
You can also use the same steps to configure the Public API, choosing an appropriate profile name and using the Public API base URL (https://api.katapult.io/public/v1).
Follow the steps below to get RESTish configured and ready to use with Katapult.
Create a new API profile
Running the following command will configure a new API profile with restish.
Profile Name
You can choose any name in place of katapult-core if you wish.
We will use this name for the rest of the guide.
restish api configure katapult-core https://api.katapult.io/core/v1
Edit the new profile
This command will launch an interactive prompt. Select Edit profile default:
? Select option [Use arrows to move, type to filter]
Change base URI (https://api.katapult.io/core/v1)
Add profile
> Edit profile default
Save and exit
In the Next prompt, Choose Add header:
? Select option Edit profile default
? Select option for profile `default` [Use arrows to move, type to filter]
> Add header
Add query param
Add custom base URL
Set up auth
Finished with profile
Add the Authorization header with your API key.
You can find your API key in the Katapult dashboard:
? Select option Edit profile default
? Select option for profile `default` Add header
? Header name Authorization
? Header value (optional) Bearer <api-key-here>
Now you should be able to select Finished with profile and then Save and exit!
Use RESTish
List available commands
You will interact with the API using a subset of commands on restish katapult-core, running this will list all commands available to you:
View example output
restish katapult-core
Welcome to the documentation for the Katapult Core API
Usage:
restish katapult-core [flags]
restish katapult-core [command]
Virtual Machine Network Interfaces Commands:
get-v-m-n-i-v-m-n-i Get virtual machine network interface
get-virtual-machine-network-interface Get virtual machine network interface by network
get-virtual-machine-network-interface-available-ips-address-version Get addresses available for network interface
get-virtual-machine-network-interfaces List virtual machine network interfaces
patch-virtual-machine-network-interface-update-speed-profile Update the network speed profile for a virtual machine network interface
post-virtual-machine-network-interface-allocate-ip Allocate an IP address
post-virtual-machine-network-interface-allocate-new-ip Allocate a new IP address
Address Lists Commands:
delete-address-list Delete address list
delete-address-list-entry Delete address list entry
get-address-list Get address list
get-address-list-entries List address list entries
get-address-list-entry Get address list entry
get-address-lists List global address lists
get-organization-address-lists List address lists
patch-address-list Update address list
patch-address-list-entry Update address list entry
post-address-list-entries Create address list entry
post-organization-address-lists Create address list
Disk Template Versions Commands:
get-disk-template-version Get disk template version
get-disk-template-version-spec Get disk template version spec
get-disk-template-versions List disk template versions
GPU Types Commands:
get-data-center-gpu-types List GPU types for Data Center
get-gpu-type Get GPU type
get-gpu-types List GPU types
Disks Commands:
delete-disk Delete disk
get-disk Get disk
get-organization-disks List disks
get-virtual-machine-disks List virtual machine disks
patch-disk Update disk
post-disk-assign Assign disk to virtual machine
post-disk-attach Attach disk to virtual machine
post-disk-detach Detach disk from virtual machine
post-disk-unassign Unassign disk from virtual machine
post-organization-disks Create disk
put-disk-io-profile Change disk IO profile
put-disk-resize Resize disk
Countries Commands:
get-countries List countries
get-country Get country
Organizations Commands:
get-organization Get organization
get-organization-managed List managed organizations
get-organization-policy-limits Get organization policy limits
get-organization-users-with-access List organization users
get-organizations List organizations
post-organization-managed Create managed organization
Data Centers Commands:
get-data-center Get data center
get-data-center-default-network Get default network of data center
get-data-centers List data centers
Disk Backup Policies Commands:
delete-disk-backup-policy Delete disk backup policy
delete-disk-backup-policy-schedule Schedule delete disk backup policy
get-disk-backup-policy Get disk backup policy
get-disk-disk-backup-policies List disk backup policies for disk
get-organization-disk-backup-policies List disk backup policies
get-virtual-machine-disk-backup-policies List disk backup policies for virtual machine
patch-disk-backup-policy Update a disk backup policy
post-disk-disk-backup-policies Create disk backup policy for disk
post-virtual-machine-disk-backup-policies Create disk backup policy for Virtual Machine
Certificates Commands:
get-certificate Get certificate
get-organization-certificates List certificates
Tags Commands:
delete-tag Delete a tag
get-organization-tags List tags
get-tag Get tag
patch-tag Update a tag
post-organization-tags Create a tag
Networks Commands:
get-network Get Network
get-organization-available-networks List networks
Virtual Machines Commands:
delete-virtual-machine Delete virtual machine
get-organization-virtual-machines List virtual machines
get-virtual-machine Get virtual machine
get-virtual-machine-authorized-keys Get authorized keys for a virtual machine
get-virtual-machines-builds-virtual-machine-build Get virtual machine build
patch-virtual-machine Update a Virtual Machine
post-organization-virtual-machines-build Build virtual machine
post-organization-virtual-machines-build-from-spec Build virtual machine (from spec)
post-virtual-machine-allocate-ip Allocate an IP Address
post-virtual-machine-console-sessions Create console session
post-virtual-machine-reset Reset virtual machine
post-virtual-machine-shutdown Shutdown virtual machine
post-virtual-machine-start Start virtual machine
post-virtual-machine-stop Stop virtual machine
put-virtual-machine-flexible-resources Change flexible resources
put-virtual-machine-package Change package
DNS Zones Commands:
delete-dns-record Delete DNS record
delete-dns-zone Delete DNS zone
get-dns-record Get DNS record
get-dns-zone Get DNS zone
get-dns-zone-records List DNS records
get-organization-dns-zones List DNS zones
get-organization-dns-zones-nameservers List nameservers
patch-dns-record Update DNS record
patch-dns-zone Update DNS zone
post-dns-zone-records Create DNS record
post-dns-zone-verify Verify DNS zone
post-organization-dns-zones Create DNS zone
Load Balancers Commands:
delete-load-balancer Delete load balancer
delete-load-balancers-rules-load-balancer-rule Delete load balancer rule
get-load-balancer Get load balancer
get-load-balancer-rules List load balancer rules
get-load-balancers-rules-load-balancer-rule Get load balancer rule
get-organization-load-balancers List load balancers
patch-load-balancer Update load balancer
patch-load-balancers-rules-load-balancer-rule Update load balancer rule
post-load-balancer-rules Create load balancer rule
post-organization-load-balancers Create load balancer
Security Groups Commands:
delete-security-group Delete security group
delete-security-groups-rules-security-group-rule Delete security group rule
get-organization-security-groups List security groups
get-security-group Get security group
get-security-group-rules List security group rules
get-security-groups-rules-security-group-rule Get security group rule
patch-security-group Update security group
patch-security-groups-rules-security-group-rule Update security group rule
post-organization-security-groups Create security group
post-security-group-rules Create security group rule
Virtual Machine Groups Commands:
delete-virtual-machine-group Delete a virtual machine group
get-organization-virtual-machine-groups List virtual machine groups
get-virtual-machine-group Get virtual machine group
patch-virtual-machine-group Update a virtual machine group
post-organization-virtual-machine-groups Create a virtual machine group
API Tokens Commands:
delete-api-token Delete organization API token
get-organization-api-tokens List organization API tokens
patch-api-token Update organization API token
post-api-token-regenerate-secret Regenerate organization API token secret
post-organization-api-tokens Create API token for organization
Trash Objects Commands:
delete-trash-object Purge a trash object
get-organization-trash-objects List trash objects
get-trash-object Get trash object
post-organization-trash-objects-purge-all Purge all trash objects
post-trash-object-restore Restore a trash object
Zones Commands:
get-zone Get zone
get-zones List zones
Network Speed Profiles Commands:
get-organization-network-speed-profiles List network speed profiles
File Storage Volumes Commands:
delete-file-storage-volume Delete file storage volume
get-file-storage-volume Get file storage volume
get-organization-file-storage-volumes List file storage volumes
patch-file-storage-volume Update file storage volume
post-organization-file-storage-volumes Create file storage volume
IP Addresses Commands:
delete-ip-address Release an IP address
get-ip-address Get IP address
get-organization-ip-addresses List IP addresses
patch-ip-address Update IP address
post-ip-address-unallocate Unallocate an IP address
post-organization-ip-addresses Create IP Address
Country States Commands:
get-country-country-states List country states
get-country-state Get country state
Currencies Commands:
get-currencies List currencies
get-currency Get currency
Virtual Machine Packages Commands:
get-virtual-machine-package Get virtual machine package
get-virtual-machine-packages List virtual machine packages
Users Commands:
get-users-current Get current user details
post-invalidate-linked-web-session Invalidate linked web session
Operating Systems Commands:
get-operating-system Get operating system
get-operating-systems List operating systems
Disk IO Profiles Commands:
get-organization-disk-io-profiles List disk IO profiles
SSH Keys Commands:
delete-ssh-key Delete SSH key
get-organization-ssh-keys List organization SSH keys
post-organization-ssh-keys Add organization SSH key
Tasks Commands:
get-task Get Task
Disk Templates Commands:
get-disk-template Get disk template
get-organization-disk-templates List disk templates
Flags:
-h, --help help for katapult-core
Global Flags:
--rsh-ca-cert string Path to a PEM encoded CA cert
--rsh-client-cert string Path to a PEM encoded client certificate
--rsh-client-key string Path to a PEM encoded private key
-f, --rsh-filter string Filter / project results using shorthand query
-H, --rsh-header stringArray Add custom header
--rsh-ignore-status-code Do not set exit code from HTTP status code
--rsh-insecure Disable SSL verification
--rsh-no-cache Disable HTTP cache
--rsh-no-paginate Disable auto-pagination
-o, --rsh-output-format string Output format [auto, json, table, ...] (default "auto")
-p, --rsh-profile string API auth profile (default "default")
-q, --rsh-query stringArray Add custom query param
-r, --rsh-raw Output result of query as raw rather than an escaped JSON string or list
--rsh-retry int Number of times to retry on certain failures (default 2)
-s, --rsh-server string Override scheme://server:port for an API
-t, --rsh-timeout duration Timeout for HTTP requests
-v, --rsh-verbose Enable verbose log output
Use "restish katapult-core [command] --help" for more information about a command.
Command Line Completion
You can also setup command line completion for restish!
View setup info here.
Example commands
Below are some examples of commands you can run with restish katapult-core.
These commands will contain some placeholders like <your-org-subdomain-here>, you should replace these with your actual values.
These examples also use the -o json -f body flags to return just the response body in a JSON format.
-o jsonspecifies the output format as JSON.-f bodyspecifies that we only want the response body.
Get a data center
As an example of looking something up from our API, we can get a list of data centers:
restish katapult-core get-data-centers -o json -f body
{
"data_centers": [
{
"country": {
"id": "ctry_IHe4noltuwtTYrSJ",
"name": "Netherlands"
},
"id": "dc_Wm37yAq0BHhKXsPa",
"name": "Amsterdam",
"permalink": "nl-ams-01"
},
{
"country": {
"id": "ctry_6AO9tYYugvTGnd5b",
"name": "United Kingdom"
},
"id": "loc_UUhPmoCbpic6UX0Y",
"name": "London",
"permalink": "uk-lon-01"
},
{
"country": {
"id": "ctry_oD9XxMQWTLqam7Oy",
"name": "United States"
},
"id": "dc_TfDSMyVYoS3fJnSt",
"name": "New York",
"permalink": "us-nyc-01"
},
{
"country": {
"id": "ctry_oD9XxMQWTLqam7Oy",
"name": "United States"
},
"id": "dc_U3UVcwL8GKXJdsgw",
"name": "Phoenix",
"permalink": "us-azp-01"
}
]
}
Create a Tag
This example uses CLI Shorthands for building a JSON body to create a tag for an organization.
restish katapult-core post-organization-tags organization.sub_domain: <your-org-subdomain-here>, properties.color: red, properties.name: example -f body
You could also redirect an actual JSON file to the command like < input.json if you have a more complex body.
input.json
{
"organization": {
"sub_domain": "<your-org-subdomain-here>"
},
"properties": {
"color": "red",
"name": "example"
}
}
restish katapult-core post-organization-tags < input.json -f body
You will get a response like this, with the tag you created:
Response
{
tag: {
color: "red"
created_at: 1724766177
id: "tag_F2JdAtqVnojtYthm"
name: "example"
}
}
Create a shell alias
You can setup an alias in your shell to make it easier to interact with the API. For example, you could add the following to your ~/.bashrc or ~/.zshrc:
~/.bashrc OR ~/.zshrc
alias katapult-core="restish katapult-core"
This would allow you to run commands like katapult-core get-data-centers -o json -f body directly from your shell. You can also add the -o json -f body to the alias if you always want to output JSON and only care about the response body.
~/.bashrc OR ~/.zshrc
alias katapult-core="restish katapult-core -o json -f body"
Using Aliases to your advantage
You can setup shell aliases for any of the commands you use frequently!
alias katapult-core="restish katapult-core -o json -f body"
Example alias for getting organization virtual machines by sub-domain
alias katapult-vms="katapult-core get-organization-virtual-machines --organization[sub-domain]"