https://github.com/ans-group/cli
Command line utility for accessing ANS services/APIs
https://github.com/ans-group/cli
cli hacktoberfest
Last synced: 4 months ago
JSON representation
Command line utility for accessing ANS services/APIs
- Host: GitHub
- URL: https://github.com/ans-group/cli
- Owner: ans-group
- License: mit
- Created: 2019-02-28T15:54:23.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-04-17T13:13:57.000Z (about 1 year ago)
- Last Synced: 2025-04-18T03:20:34.436Z (about 1 year ago)
- Topics: cli, hacktoberfest
- Language: Go
- Homepage:
- Size: 3.51 MB
- Stars: 11
- Watchers: 2
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ANS CLI
[](LICENSE)
This is the official ANS command-line client, allowing for querying and controlling
supported ANS services.
The client utilises ANS APIs to provide access to most service features. You should refer to the
[Getting Started](https://developers.ukfast.io/getting-started) section of the API documentation before
proceeding below.
## Demo
### SafeDNS
### eCloud VPC
## Installation
The CLI is distributed as a single binary, and is available for Windows, Linux and Mac. This binary
should be downloaded and placed into a directory included in your `PATH`. This would typically
be `/usr/local/bin` on most Linux distributions
Pre-compiled binaries are available at [Releases](https://github.com/ans-group/cli/releases)
### Building from source
Install the dependencies, golang and make, then build from the Makefile.
```
# make
```
To copy to /usr/local/bin, as root or using sudo
```
# make install
```
## Getting started
To get started, we will define a single environment variable to store our API key:
Bash:
> export ANS_API_KEY="iqmxgom0kairfnxzcopte5hx"
PowerShell:
> $env:ANS_API_KEY="iqmxgom0kairfnxzcopte5hx"
And away we go!
```
> ans safedns zone record show example.co.uk 3337874
+---------+--------------------+------+---------+---------------------------+----------+-----+
| ID | NAME | TYPE | CONTENT | UPDATED AT | PRIORITY | TTL |
+---------+--------------------+------+---------+---------------------------+----------+-----+
| 3337874 | test.example.co.uk | A | 1.2.3.4 | 2019-03-19T16:33:55+00:00 | 0 | 0 |
+---------+--------------------+------+---------+---------------------------+----------+-----+
```
## Configuration
The CLI utilises the common config from the underlying SDK, with details available [here](https://github.com/ans-group/sdk-go#config).
### Schema
The CLI adds the following to the config schema:
* `api_debug`: (bool) Specifies for debug messages to be output to stderr
* `api_pagination_perpage` (int) Specifies the per-page for paginated requests
### Contexts
Contexts can be defined in the config file to allow for different sets of configuration to be defined. The current context can be overridden with the `--context` flag
### Commands
The configuration file can be manipulated using the `config` subcommand, for example:
```
> ans config context update --current --api-key test1
> ans config context update someothercontext --api-key test1
> ans config context switch someothercontext
```
## Output Formatting
The output of all commands is determined by a single global flag `--output` / `-o`.
In addition to output, there are several output modifier flags which are explained below.
The default output format can be set in the configuration file using the `output.default` field, e.g.
```yaml
output:
default: json
```
### Table (Default)
The default output format for the CLI is `Table`, which will be used when the value of the `--output` flag
is `table` or unspecified:
```
> ans safedns zone record list example.co.uk
+---------+--------------------+------+-----------------------------------------------------------------------+---------------------------+----------+-------+
| ID | NAME | TYPE | CONTENT | UPDATED AT | PRIORITY | TTL |
+---------+--------------------+------+-----------------------------------------------------------------------+---------------------------+----------+-------+
| 3337865 | ns0.ans.uk | NS | 185.226.220.128 | 2019-03-19T16:31:48+00:00 | 0 | 0 |
| 3337868 | ns1.ans.uk | NS | 185.226.221.128 | 2019-03-19T16:31:48+00:00 | 0 | 0 |
| 3337871 | example.co.uk | SOA | ns0.ans.uk support.ans.co.uk 2019031901 7200 3600 604800 86400 | 2019-03-19T16:31:48+00:00 | 0 | 86400 |
| 3337874 | test.example.co.uk | A | 1.2.3.4 | 2019-03-19T16:33:55+00:00 | 0 | 0 |
+---------+--------------------+------+-----------------------------------------------------------------------+---------------------------+----------+-------+
```
The [Property Modifier](#property) is available for this format
The table output style can be customised using the `output.table.style` field in your configuration file. This directive accepts either `ascii` (default) or `unicode`, which will change the table output to use unicode characters for borders and lines.
```yaml
output:
table:
style: unicode
```
### List
Results can be output as a list using the `list` format:
```
> ans safedns zone record show example.co.uk 3337874 --output list
id : 3337874
name : test.example.co.uk
type : A
content : 1.2.3.4
updated_at : 2019-03-19T16:33:55+00:00
priority : 0
ttl : 0
```
The [Property Modifier](#property) is available for this format
### JSON
Results can be output in JSON using the `json` format:
```
> ans safedns zone record show example.co.uk 3337874 --output json
[{"id":3337874,"template_id":0,"name":"test.example.co.uk","type":"A","content":"1.2.3.4","updated_at":"2019-03-19T16:33:55+00:00","ttl":0,"priority":0}]
```
You can also the use the `json-pretty` format to output pretty-printed JSON:
```
> ans safedns zone record show example.co.uk 3337874 --output json-pretty
[
{
"id": 3337874,
"template_id": 0,
"name": "test.example.co.uk",
"type": "A",
"content": "1.2.3.4",
"updated_at": "2019-03-19T16:33:55+00:00",
"ttl": 0,
"priority": 0
}
]
```
### YAML
Results can be output in YAML using the `yaml` format:
```
> ans safedns zone record show example.co.uk 3337874 --output yaml
- id: 3337874
templateid: 0
name: test.example.co.uk
type: A
content: 1.2.3.4
updatedat: "2019-03-19T16:33:55+00:00"
ttl: 0
priority: 0
```
### Value
Results can be output with a value or set of values using the `value` format:
```
> ans safedns zone record show example.co.uk 3337874 --output value
3337874 test.example.co.uk A 1.2.3.4 2019-03-19T16:33:55+00:00 0 0
```
```
> ans safedns zone record show example.co.uk 3337874 --output value --property id
3337874
```
The [Property Modifier](#property) is available for this format
### CSV
Results can be output as CSV using the `csv` format:
```
> ans safedns zone record show example.co.uk 3337874 --output csv
id,name,type,content,updated_at,priority,ttl
3337874,test.example.co.uk,A,1.2.3.4,2019-03-19T16:33:55+00:00,0,0
```
The [Property Modifier](#property) is available for this format
### Template
Results can be output using a supplied Golang template string using the `template` format
in conjunction with output arguments, e.g.
```
> ans safedns zone record list example.co.uk --output template="Record name: {{ .Name }}, Type: {{ .Type }}"
Record name: ns0.ans.uk, Type: NS
Record name: ns1.ans.uk, Type: NS
Record name: example.co.uk, Type: SOA
Record name: test.example.co.uk, Type: A
```
### JSON path
Results can be output via JSON Path using the `jsonpath` format
in conjunction with output arguments, e.g.
```
> ans safedns zone record list example.co.uk --output jsonpath="{[*].name}"
example.co.uk example.co.uk example.co.uk test.example.co.uk
```
## Output modifiers
### Property
Some output formats support the `--property` output modifier.
Required properties can be specified with the `--property` format modifer flag:
```
> ans safedns zone record show example.co.uk 3337874 --output value --property name
test.example.co.uk
```
The property modifier accepts a comma-delimited list of property names, and is also repeatable:
```
> ans safedns zone record show example.co.uk 3337874 --output value --property id,name --property content
3337874 test.example.co.uk 1.2.3.4
```
The property modifier also accepts globbing e.g. `*`, `some*`, `*thing`
## Filtering
When using `list` commands, filtering is available via the `--filter` flag. Additionally, optional operators are available.
### Examples
```
--filter id=123
--filter id:lt=10
```
Additionally, the `lk` filter is inferred when a glob `*` is included in the filter value (when operator is omitted)
## Sorting
When using `list` commands, sorting is available via the `--sort` flag.
### Examples
```
--sort id
--sort id:desc
```
## Updates
The CLI has self-update functionality, which can be invoked via the command `update`:
```
> ans update
```
This command in-place updates the CLI, with the old binary moved to `ans.old` (`ans.old.exe` on Windows), should roll-back be required.
### Migrating from the UKFast CLI
If you are upgrading from the old `ukfast` client, you will need to install this client from scratch. You will need to rename `~/.ukfast.yml` to `~/.ans.yml` and ensure any environment variables are updated to use the new `ANS_` prefix, e.g. `UKF_ECLOUD_VPC=true` becomes `ANS_ECLOUD_VPC=true`.
## Shell autocompletions
The CLI supports generating shell completions for the following shells:
* Bash
* Zsh
* PowerShell
The commands at `ans completion ` provide help for installation on different platforms
## Releasing
`goreleaser` is used to release the CLI on Github.
First, we'll obtain our GPG fingerprint:
```
gpg -k
```
Next, we'll set some environment variables - including GPG fingerprint from above:
```
export GITHUB_TOKEN=
export GPG_FINGERPRINT=
export GPG_TTY=$(tty)
```
We'll then need to cache our GPG passphrase:
```
gpg --armor --detach-sign -n main.go
```
Finally push a new tag and invoke `goreleaser`:
```
git tag v1.10.0
git push --tags
goreleaser --rm-dist
```
## eCloud VPC resources
eCloud VPC resource commands are available by default under the `ecloud` subcommand.
To display only VPC commands, the following environment variable can be set:
```
> export ANS_ECLOUD_VPC=true
```
To display only original commands, the following environment variable can be set:
```
> export ANS_ECLOUD=true
```