README.md
1# lw (liquidweb-cli)
2Official command line interface for the LiquidWeb API
3```
4CLI interface for LiquidWeb.
5
6Command line interface for interacting with LiquidWeb services via
7LiquidWeb's Public API.
8
9If this is your first time running, you will need to setup at least
10one auth context. An auth context contains authentication data for
11accessing your LiquidWeb account. As such one auth context represents
12one LiquidWeb account. You can have multiple auth contexts defined.
13
14To setup your first auth context, you run 'auth init'. For further
15information on auth contexts, be sure to checkout 'help auth' for a
16list of capabilities.
17
18As always, consult the various subcommands for specific features and
19capabilities.
20
21Usage:
22 lw [command]
23
24Available Commands:
25 asset All things assets
26 auth authentication actions
27 cloud Interact with LiquidWeb's Cloud platform
28 completion Generate completion script
29 dedicated All things dedicated server
30 help Help about any command
31 network network actions
32 plan Process YAML plan file
33 ssh SSH to a Server
34 version show build information
35
36Flags:
37 --config string config file (default is $HOME/.liquidweb-cli.yaml)
38 -h, --help help for lw
39 --use-context string forces current context, without persisting the context change
40
41Use "lw [command] --help" for more information about a command.
42```
43## Obtaining prebuilt binaries
44
45Head on over to the [releases page](https://github.com/liquidweb/liquidweb-cli/releases) to get prebuilt binaries for your platform.
46
47## Building from source
48
49You can build lw from source by running `make build` from the root of this repository. The resulting program will be located at `./_exe/lw`.
50You can also build+install lw onto your system in the ordinary `go install` way. To do this, either just run `go install` from the root of this repository,
51or `make install`. If you run `make` with no arguments, this will be the default action.
52
53## First Time Setup
54The first time you use lw, you will need to setup an auth context. An auth context holds authentication related data for a specific LiquidWeb account. You can follow a guided questionnaire to add your auth contexts if you pass arguments `auth init` to lw. By default contexts are stored in `~/.liquidweb-cli.yaml` or `%APPDATA%/.liquidweb-cli.yaml` on Windows.
55
56## Adding auth contexts later
57If you end up wanting to add an auth context later on, you can do so with `auth add-context`. You can find the usage documentation in `help auth add-context`.
58
59## Removing auth contexts later
60If you end up wanting to remove an auth context later on, you can do so with `auth remove-context`. You can find the usage documentation in `help auth remove-context`.
61
62## Modifying auth contexts later
63If you end up wanting to modify an auth context later on, you can do so with `auth update-context`. You can find the usage documentation in `help auth update-context`.
64
65## LiquidWeb Cloud
66The Cloud features you can use in manage.liquidweb.com on your Cloud Servers you can do with this command line tool. See `help cloud` for a full list of features and capabilities.
67
68## Plans
69
70A plan is a pre-defined yaml with optional template variables that can be used to
71repeate specific tasks. Fields in the yaml file match the params you would send
72to the command.
73
74Current commands supported in a `plan` file:
75
76- cloud server create
77- cloud server resize
78- cloud template restore
79- ssh
80
81Example:
82
83`lw plan --file plan.yaml`
84
85```
86---
87cloud:
88 server:
89 create:
90 - type: "SS.VPS"
91 password: "{{- generatePassword 25 -}}"
92 template: "UBUNTU_1804_UNMANAGED"
93 zone: 27
94 hostname: "web1.somehost.org"
95 ips: 1
96 public-ssh-key: "your public ssh key here
97 config-id: 88
98 bandwidth: "SS.5000"
99```
100
101You can find more examples of plans in `examples/plans`.
102
103### Plan Variables
104
105Plan yaml can make use of golang's template variables. Allows variables to be passed on the
106command line and it can access environment variables.
107
108#### Environment Variables
109Envonrment variables are defined as `.Env.VARNAME`. On most linux systems and shells you can
110get the logged in user with `{{ .Env.USER }}`.
111
112#### User Defined Variables
113If you wanted to pass user defined variables on the command line you would use the `--var` flag
114(multiple `--var` flags can be passed). For example, if you wanted to generate the hostname of
115`web3.somehost.org` you would use the following command and yaml:
116
117`lw plan --file play.yaml --var node=3 --var role=web`
118
119```
120 hostname: "{{- .Var.role -}}{{- .Var.node -}}.somehost.org"
121```
122
123
124#### Functions
125
126The following functions are defined to be called from a plan template:
127
128- generatePassword <length>
129
130For example, to generate a random 25 character password:
131
132```password: "{{- generatePassword 25 -}}"```
133
134- now
135
136Gives access to a Golang `time` object using your local machine's clock.
137
138Simple example:
139
140```
141 hostname: "web1.{{- now.Year -}}{{- now.Month -}}{{- now.Day -}}.somehost.org"
142```
143
144- hex
145
146Convert a number to hexidecimal.
147
148