- Getting Started
- Using AIS CLI
- AIS CLI Shell Autocomplete
- CLI reference
- Info For Developers
- Default flag and argument values via environment variables
AIS CLI (command-line interface) is intended to easily control and monitor every aspect of the AIS cluster life-cycle. In addition, CLI provides dataset management commands, commands to read and write data, and more.
TL;DR: see section CLI reference below to quickly locate useful commands. There's also a (structured as a reference) list CLI resources with numerous examples and usage guides that we constantly keep updating.
Run make cli
in AIStore repo root directory to install AIS CLI binary in your $GOPATH/bin
directory.
You can also install shell autocompletions for AIS CLI with make cli-autocompletions
.
The rest of the README assumes that user's
PATH
environment variable contains$GOPATH/bin
directory. Runexport PATH=$PATH:$GOPATH/bin
if this is not the case for you. You can read more about GOPATH environment variable here.
On first use, CLI will create config.json
file in $XDG_CONFIG_HOME/ais
(or if XDG_CONFIG_HOME
is not set, in ~/.config/ais
) directory.
The content of the file presents as follows:
{
"cluster": {
"url": "http://127.0.0.1:8080",
"default_ais_host": "http://127.0.0.1:8080",
"default_docker_host": "http://172.50.0.2:8080"
},
"timeout": {
"tcp_timeout": "60s",
"http_timeout": "0s"
},
"auth": {
"url": "http://127.0.0.1:52001"
},
"default_provider": "ais"
}
Simply change config file so next time CLI will use updated values.
To get the list of commands, run following command:
$ ais --help
To check if the CLI can correctly contact the cluster and to get cluster status, run following command:
$ ais show cluster
Besides a set of options specific for each command, AIS CLI provides global options:
--no-color
- by default AIS CLI displays messages with colors (e.g, errors are printed in red color). Colors are automatically disabled if CLI output is redirected or environment variableTERM=dumb
is set. To disable colors in other cases, pass--no-color
to the application.
Please note that the place of a global options in the command line is fixed. Global options must follow the application name directly. At the same time, the location of a command-specific option is arbitrary: you can put them anywhere. Examples:
$ # Correct usage of global and command-specific options.
$ ais --no-color ls ais://bck --props all
$ ais --no-color ls --props all ais://bck
$
$ # Incorrect usage of a global option.
$ ais bucket ls ais://bck --props all --no-color
The CLI tool supports bash
and zsh
auto-complete functionality.
When running install.sh
you will be asked if you want to install autocompletions.
To install them manually, run bash autocomplete/install.sh
.
To uninstall autocompletions, run bash autocomplete/uninstall.sh
.
- Create, destroy, list, and other operations on buckets
- GET, PUT, APPEND, PROMOTE, and other operations on objects
- Cluster and Node management
- Mountpath (Disk) management
- Attach, Detach, and monitor remote clusters
- Start, Stop, and monitor downloads
- Distributed Sort
- User account and access management
- Xaction (Job) management
- Search CLI Commands
The CLI uses urfave/cli framework.
Currently, the CLI has the format of ais <command> <resource>
.
To add a new resource to an existing command,
- Create a subcommand entry for the resource in the command object
- Create an entry in the command's flag map for the new resource
- Register flags in the subcommand object
- Register the handler function (named
XXXHandler
) in the subcommand object
To add a new resource to a new command,
- Create a new Go file (named
xxx_hdlr.go
) with the name of the new command and follow the format of existing files - Once the new command and subcommands are implemented, make sure to register the new command with the CLI (see
setupCommands()
inapp.go
)
Provider's syntax provider://BUCKET_NAME
(referred as BUCKET
) works across all commands.
For more details, please refer to each specific command's documentation.
Provider can be omitted if the default_provider
config value is set (in such case the config value will be used implicitly).
Supported backend providers currently include:
ais://
- AIStore provideraws://
ors3://
- Amazon Web Servicesazure://
oraz://
- Azure Blob Storagegcp://
orgs://
- Google Cloud Storagehdfs://
- HDFS Storageht://
(* see below) - HTTP(S) datasets
See also: Backend Providers See also: Buckets