jamesclonk/vultr

:penguin: Vultr CLI and API client library

vultr

Vultr CLI and API client library, written in Go

Screenshot

Everybody likes screenshots, even of command line tools.. 😄

Installation

• Download the latest release for your OS: https://github.com/JamesClonk/vultr/releases
• Unzip the file
• Place the vultr binary somewhere into your PATH
• Export your Vultr API key into a VULTR_API_KEY env variable. You can get the API key from the admin panel

$ export VULTR_API_KEY=87dFbC91rJjkL/18zJEQxS

• Run it

$ vultr version
Client version:         2.0.3
Vultr API endpoint:     https://api.vultr.com/
Vultr API version:      v1
OS/Arch (client):       linux/amd64
Go version:             go1.16

---

Installation via brew

Homebrew users can install by:

$ brew install vultr

Installation from source

• Install the latest version of Go
• Make sure your GOPATH is set
• Add $GOPATH/bin to your PATH
• Use "go get" to download, compile and install the source

$ go get github.com/JamesClonk/vultr

• Export your Vultr API key into a VULTR_API_KEY env variable. You can get the API key from the admin panel

$ export VULTR_API_KEY=89dFbb91rGjkL/12zJEQxS

• Run it

$ vultr version
Client version:         2.0.3
Vultr API endpoint:     https://api.vultr.com/
Vultr API version:      v1
OS/Arch (client):       linux/amd64
Go version:             go1.16

---

Usage

Vultr CLI is a command line tool for using the Vultr API. It allows you to create and manage your virtual machines, SSH public keys, snapshots and startup scripts on your Vultr account. You can also use it to directly SSH into a Vultr virtual machine through the vultr ssh command.

Here a some usage examples:

---

show help text for a command

$ vultr snapshot --help

Usage: vultr snapshot  COMMAND [arg...]

modify snapshots

Commands:
  create       create a snapshot from an existing virtual machine
  delete       delete a snapshot
  list         list all snapshots on current account

Run 'vultr snapshot COMMAND --help' for more information on a command

---

list available plans for region

$ vultr plans -r 9

VPSPLANID NAME                                VCPU  RAM   DISK  BANDWIDTH PRICE
30        1024 MB RAM,20 GB SSD,2.00 TB BW    1     1024  20    2.00      7.00
29        768 MB RAM,15 GB SSD,1.00 TB BW     1     768   15    1.00      5.00
3         2048 MB RAM,40 GB SSD,3.00 TB BW    2     2048  40    3.00      15.00
28        8192 MB RAM,120 GB SSD,5.00 TB BW   4     8192  120   5.00      70.00
27        4096 MB RAM,65 GB SSD,4.00 TB BW    2     4096  65    4.00      35.00

---

add SSH public key

$ vultr sshkey create -n sampleKey --key="$(cat ~/.ssh/id_rsa.pub)"

SSH key create success!

SSHKEYID        NAME        KEY
24c81f53be692   sampleKey   ssh-rsa AAAB3NzaC1yc2EQABAQClpsNAM+huOB2dpxM..

---

create new virtual machine

$ vultr server create -n "test-server" -r 9 -p 29 -o 127

Virtual machine create success!

SUBID           NAME            DCID    VPSPLANID       OSID
1685097         test-server     9       29              127

---

show information about virtual machine

$ vultr server show 1685097

Id (SUBID):             1685097
Name:                   test-server
Operating system:       CentOS 6 x64
Status:                 active
Power status:           running
Location:               Frankfurt
Region (DCID):          9
VCPU count:             1
RAM:                    768 MB
Disk:                   Virtual 15 GB
Allowed bandwidth:      1000
Current bandwidth:      0
Cost per month:         5.00
Pending charges:        0.01
Plan (VPSPLANID):       29
IP:                     107.62.131.240
Netmask:                255.255.254.0
Gateway:                107.62.131.1
Internal IP:
#1 IPv6 IP:
#1 IPv6 Network:        ::
#1 IPv6 Network Size:   0
Created date:           2015-02-08 12:36:36
Default password:       sbiecxo8yk!5
Auto backups:           no
KVM URL:                https://my.vultr.com/subs/vps/novnc/api.php?data=ILXS..

---

SSH into virtual machine

$ vultr ssh 1685097

Welcome to Ubuntu 14.04.1 LTS (GNU/Linux 3.13.0-37-generic x86_64)

 * Documentation:  https://help.ubuntu.com/
Last login: Thu Oct 16 21:49:35 2014 from 10.0.2.2
root@vultr:~#

---

vultr's Issues

[Feature Request] Add go modules support

Self update feature

It would be nice to add a self-update feature, something similar to composer's. I think it should be pretty straight forward since there's only one file but it's up to you to decide. Thanks.

Show used bandwidth in summary

When showing all servers, it would be nice if the used bandwidth for each would be listed too.

So instead of just showing the number that the instance allows:

BANDWIDTH
1000

show the used bandwidth too:

BANDWIDTH
40.2/1000

The field should offer enough space to display this.

Block storage?

https://www.vultr.com/features/blockstorage/

incorporate /v1/app/list?

Example Request:
curl https://api.vultr.com/v1/app/list

Example Response:
{
"1": {
"APPID": "1",
"name": "LEMP",
"short_name": "lemp",
"deploy_name": "LEMP on CentOS 6 x64",
"surcharge": 0
},
"2": {
"APPID": "2",
"name": "WordPress",
"short_name": "wordpress",
"deploy_name": "WordPress on CentOS 6 x64",
"surcharge": 0
}
}

API breakage between 1.12.0 and 1.13.0

Thanks for providing this package!

https://github.com/JamesClonk/vultr/blob/1.12.0/lib/dns.go has “type DnsDomain”
https://github.com/JamesClonk/vultr/blob/1.13.0/lib/dns.go has “type DNSDomain”

This change has caused issues in the lego Debian packaging: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=869270

Could you provide type aliases and wrapper functions to prevent API breakages in the future please?

Also, your version number looks like semantic versioning. But, as per the following quote from http://semver.org, the 1.13.0 release is a clear violation (it makes an incompatible API change without incrementing the major version). Are you not using semantic versioning? If so, that’d be worth calling out in the README.

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

Add CLI flag for JSON output

Bash completion

Would be super awesome if we didn't have to type or copy-paste the ids all the time.
Also helps to find commands faster 👍

App Info Feature

The Vultr API has a 'get_app_info' request for finding out the details of the application installed. at https://www.vultr.com/api/#server_get_app_info I couldn't find any feature related to this within the Vultr CLI.

Use case:
I spin up a OpenVPN server, and the login credentials (different to the VPS credentials) are detailed within this API call.

create a server from snapshot does not work

test case1:

        vultr server create --name="test" --region=19 --plan=201 --name="test" --os=193 --sshkey="${ssh_key}" --hostname="test" --tag="test" --private-networking=true --autobackups=false --notify-activate=true --snapshot="${snapshot_id}"

server was created, but:

1. it was created not using the snapshot
2. the ssh key specified was not used

test case2:
a new box creation: the only difference is the --snapshot argument
vultr server create --name="test" --region=19 --plan=201 --name="test" --os=193 --sshkey="${ssh_key}" --hostname="test" --tag="test" --private-networking=true --autobackups=false --notify-activate=true

1. it is working perfectly
2. key was used

Add tag option to server create cmd

Split the CLI client and API client library into separate repositories

Software libraries should not be in the same repo as their invoking programs(The CLI Client in this case). One package per repo would be much cleaner.

An example of this can be seen in the Digital Ocean Go API Client lib and their CLI tool.

Go 1.15: conversion from int to string yields a string of one rune, not a string of digits (did you mean fmt.Sprint(x)?)

Go 1.15 rc1 on Fedora Rawhide:

Testing    in: /builddir/build/BUILD/vultr-2.0.1/_build/src
         PATH: /builddir/build/BUILD/vultr-2.0.1/_build/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/sbin
       GOPATH: /builddir/build/BUILD/vultr-2.0.1/_build:/usr/share/gocode
  GO111MODULE: off
      command: go test -buildmode pie -compiler gc -ldflags "-X github.com/JamesClonk/vultr/version=2.0.1 -extldflags '-Wl,-z,relro -Wl,--as-needed  -Wl,-z,now -specs=/usr/lib/rpm/redhat/redhat-hardened-ld '"
      testing: github.com/JamesClonk/vultr
github.com/JamesClonk/vultr/lib
# github.com/JamesClonk/vultr/lib
./servers.go:695:17: conversion from int to string yields a string of one rune, not a string of digits (did you mean fmt.Sprint(x)?)
./servers.go:696:17: conversion from int to string yields a string of one rune, not a string of digits (did you mean fmt.Sprint(x)?)
./servers.go:697:17: conversion from int to string yields a string of one rune, not a string of digits (did you mean fmt.Sprint(x)?)
FAIL	github.com/JamesClonk/vultr/lib [build failed]

See golang/go#32479

API updates Feb 2016

/v1/server/list

New field: server_state
more detailed status of: none | locked | installingbooting | isomounting | ok

Deprecated fields: v6_network, v6_main_ip, and v6_network_size
Replaced by: v6_networks JSON object array

api-rate-limit upped from 1/sec to 2/sec 😆 WOW

Whenever you have some spare time... 😄

Cannot customize hostname

I am getting the error message Server add failed: Invalid hostname for any hostname name I use for the argument --hostname.

For 'vultr server create' make the -o flag optional if --snapshot is defined

There is a discrepancy between the Webinterface/API and this CLI; When you select a new machine to be deployed from a snapshot you don't have to provide the OS definition, but in the CLI you have to.

Example:
Create a CoreOS Stable Machine
Upgrade CoreOS to the Beta Channel
Make s Snapshot of the Server
When trying to create a Server with: vultr server create -n $SERVER_NAME -r $REGION -p $PLAN --snapshot="$SNAPSHOT" it points out that you have to specify -o
When trying to get a CoreOS Beta with: vultr server create -n $SERVER_NAME -r $REGION -p $PLAN --snapshot="$SNAPSHOT" -o 179 then /etc/coreos/update.conf contains GROUP=stable which is not desired
You can do this properly with the Vultr Webinterface and API.

Salt driver

Please consider implementing a Salt Stack driver
https://docs.saltstack.com/en/latest/topics/cloud/cloud.html

It'll be very popular, maybe Vultr would fund it!

--private-networking Multiple Private Networks

I am recieving this error when attemtping to enable private networking:

Server add failed: No NETWORKID defined, but multiple private networks exist in this location.

The issue is, that no matter what I try I can't seem to pass the NETWORKID paramater.

Any help would be greatly appreciated, thanks!

`pending_charges` has changed from `float64` to `string`

vultr.com updated theirs API, several commands doesn't work anymore.

$ vultr servers
2015/07/07 19:48:07 json: cannot unmarshal string into Go value of type float64

$ vultr server show 12345
2015/07/07 19:52:49 json: cannot unmarshal string into Go value of type float64

Rename package lib to govultr or similar

I noticed that even in your own code you aliased the package as Vultr to improve clarity. Sure, we could alias. But I believe renaming the package would be better in the long term.

"linting" fix changed API

Hi,

Commit 3e1b825 "fix all linting" actually changed the API. This, for example:

3e1b825#diff-3676638119a5a17122a453849c43b293L61

changes the function "CreateDnsRecord" to "CreateDNSRecord". That of course breaks API, and anything that uses it. Case in point, it broke lego (https://github.com/xenolf/lego).

Was this intentional?

Add to homebrew

It would be great if this could be added to homebrew!

This would make it easy to:

• Install.
• Keep up to date.

https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Formula-Cookbook.md

Feature request: make vultr use proxy env vars

I installed vultr with brew install vultr on mac and it doesn't seem to read proxy env vars (http_proxy or all_proxy):

$ vultr version
Client version:         2.0.1
Vultr API endpoint:     https://api.vultr.com/
Vultr API version:      v1
OS/Arch (client):       darwin/amd64
Go version:             go1.13.1

$ vultr info
2020/08/07 **:35:57 Your IP (**********) is not authorized to use this API key

I rely on proxies to access the internet behind a firewall - it would be great if vultr supports http or socks5 proxy!

Managed databases support

API docs:

https://www.vultr.com/api/#tag/managed-databases/operation/list-databases

Would love to see this included. (=

add support for managing the reverse dns

as described at:

• https://www.vultr.com/api/#server_reverse_set_ipv4
• https://www.vultr.com/api/#server_reverse_set_ipv6
• https://www.vultr.com/api/#server_reverse_list_ipv6
• https://www.vultr.com/api/#server_reverse_delete_ipv6

BTW, I'm trying to create a terraform provider with your library at https://github.com/rgl/terraform-provider-vultr, feel free to join :-)

Invalid server Error

Hi,

I got a invalid server error, when I try the follow steps:

Creating server from snapshot, hostname argument ignored

When creating a new server from a snapshot (with --os=164 --snapshot=ID), the --hostname parameter seems to be ignored. The newly created server always gets the same hostname as the server where the snapshot was generated from.

Not sure if this is an issue with the CLI or the Vultr API.

Rate Limit Exceeded Error

Hey I'm using the https://github.com/squat/terraform-provider-vultr library with terraform, and I keep getting rate limit exceeded errors... is there anything in your library that would let me set the retrycount or a backoff delay?

* module.firewall2.vultr_firewall_rule.icmp_rule: vultr_firewall_rule.icmp_rule: 
Error getting firewall rule (c5a8d199/1): Rate limit reached - please try your request again later.  
Current rate limit: 2 requests/sec

Sort output of Vultr Plugin (Output currently unordered)

As mentioned in title. Sorting by price seems most logical.

@JamesClonk Additionally, is this repo still maintained? If not, I will likely create a fork.

Time for new release?

Seems like master builds just fine. So is it time for a new release? This would be very much appreciated to enable Homebrew building using go 1.16 in the easiest possible way. It's the addition of go modules that's key.

To my novice eyes the only thing maybe missing for a release might be an updated README, or am I totally off here?

API key displayed plain-text when looking at usage info

Observe:

$ vultr --help

Usage: vultr [OPTIONS] COMMAND [arg...]

A Vultr CLI

Options:
  -k, --api-key=""   Vultr API-Key ($VULTR_API_KEY)
...
$ export VULTR_API_KEY=supersecretapikey
$ vultr --help            

Usage: vultr [OPTIONS] COMMAND [arg...]

A Vultr CLI

Options:
  -k, --api-key="supersecretapikey"   Vultr API-Key ($VULTR_API_KEY)
...

This isn't a huge problem, but could be the source of inadvertent key leakage in screenshots, copy/pastes, etc...

This project's license is MIT, but has a dependency which is LGPLv3

Although this project is licensed as MIT (which is awesome, thanks!), it uses at least one dependency which has a more limiting license - LGPLv3: https://github.com/juju/ratelimit
It is highly recommended to switch to a different library which gives the functionality you need but has a friendlier license, or write it on your own...

defect - vultr server delete does not work

when I use the command: vultr server delete serverid

I got prompt:
Are you sure? (Type uppercase yes): yes

But the instance is still running and vultr's console also shows the instance was not destroyed at all.

Please don't disable SSH host key checking unconditionally

vultr/cmd/commands_ssh_unix.go

Lines 15 to 16 in e2c62e5

	"-o", "UserKnownHostsFile=/dev/null",
	"-o", "StrictHostKeyChecking=no",

These two lines undermine the security of SSH significantly, I believe.

• Existing known host keys aren't checked.
• Host key verification in itself isn't performed, really.

Potential risk: man in the middle attacks, or, accidentally connecting to the wrong server (e.g. stale information, new IP, load balanced).

I would strongly suggest to leave it up to the user to accept/verify unknown host keys and to use default known hosts file, i.e. remove the two lines. It would be great if the public key generated for each Vultr instance would be exposed by Vultr's API, but it isn't, I believe, so there's not much that you can do in a client library.

(I did not go through the Windows code path here, possibly also affected.)

add confirmation when vultr server delete

I accidentally deleted a server yesterday, it would be great to have a confirmation before deleting the server, and a --yes flag to make it possible to automate it.

create 1.10 release