Skip to content

Latest commit

 

History

History
275 lines (200 loc) · 11 KB

cli.md

File metadata and controls

275 lines (200 loc) · 11 KB
layout title permalink redirect_from
post
CLI
/docs/cli
/cli.md/
/docs/cli.md/

Table of contents

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.

Getting Started

To build CLI from source, run the following two steps:

$ make cli			# 1. build CLI binary and install it into your `$GOPATH/bin` directory
$ make cli-autocompletions	# 2. install CLI autocompletions (Bash and/or Zsh)

To build with debug, run:

$ MODE=debug make cli

Alternatively, install directly from GitHub:

For example, the following command extracts CLI binary to the specified destination and, secondly, installs bash autocompletions:

$ ./deploy/scripts/install_from_binaries.sh --dstdir /tmp/www --completions

For more usage options, run: ./deploy/scripts/install_from_binaries.sh --help

You can also install bash and/or zsh autocompletions separately at any (later) time:

To uninstall autocompletions, follow the install_autocompletions.sh generated prompts, or simply run bash autocomplete/uninstall.sh.

Please note: using CLI with autocompletions enabled is strongly recommended.

Once installed, you should be able to start by running ais <TAB-TAB>, selecting one of the available (completion) options, and repeating until the command is ready to be entered.

TL;DR: see section CLI reference below to quickly locate useful commands. There's also a (structured as a reference) list of CLI resources with numerous examples and usage guides that we constantly keep updating.

TIP: when starting with AIS, ais search command may be especially handy. It will list all possible variations of a command you are maybe looking for - by exact match, synonym, or regex.

See also:

The rest of the README assumes that user's PATH environment variable contains $GOPATH/bin directory. Run export PATH=$PATH:$GOPATH/bin if this is not the case. You can find more about $GOPATH environment here.

CLI Reference

The recommended and, actually, fastest way to get started with CLI is to type ais and press <TAB-TAB>:

$ ais <TAB-TAB>
bucket       config       auth        advanced     log              alias        put         wait       rmb
object       etl          show        storage      performance      cp           start       get        search
cluster      job          help        archive      remote-cluster   create       stop        ls

These are the top-level commands as of mid-2023. Each command has its own extended help (--help) and sub-commands (which, in turn, have their respective helps and subcommands).

The list of top-level commands must give maybe the first idea of the supported functionality and functional grouping.

Following is a brief summary (that's non-exhaustive and slightly outdated):

Command Use Case
ais help All top-level commands and brief descriptions; version and build; general usage guidelines.
ais advanced Special commands for developers and advanced usage.
ais alias User-defined command aliases.
ais archive Read, write, and list archives (i.e., objects formatted as TAR, TGZ, ZIP, etc.)
ais auth Add/remove/show users, manage user roles, manage access to remote clusters.
ais bucket Create/destroy buckets, list bucket's content, show existing buckets and their properties.
ais cluster Monitor and manage AIS cluster: add/remove nodes, change primary gateway, etc.
ais config Set local/global AIS cluster configurations.
ais etl Execute custom transformations on objects.
ais job Query and manage jobs (aka eXtended actions or xactions).
ais object PUT and GET (write and read), APPEND, archive, concat, list (buckets, objects), move, evict, promote, ...
ais search Search ais commands.
ais show Monitor anything and everything: performance (all aspects), buckets, jobs, remote clusters, and more.
ais log Download ais nodes' logs or view the logs in real time.
ais storage Show capacity usage on a per bucket basis (num objects and sizes), attach/detach mountpaths (disks).
{: .nobreak}

Other CLI documentation:

Note: In CLI docs, the terms "xaction" and "job" are used interchangeably.

CLI Config

Notice:

  • CLI configuration directory: $HOME/.config/ais/cli
  • CLI configuration filename: cli.json

For the most updated system filenames and configuration directories, please see fname/fname.go source.

When used the very first time, or if the $HOME/.config/ais/cli/cli.json does not exist, the latter will be created with default parameters:

$ ais config cli --json

{
    "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",
        "client_crt": "",
        "client_crt_key": "",
        "client_ca_tls": "",
        "skip_verify_crt": false
    },
    "timeout": {
        "tcp_timeout": "60s",
        "http_timeout": "0s"
    },
    "auth": {
        "url": "http://127.0.0.1:52001"
    },
    "aliases": {
        "wait": "job wait",
        "cp": "bucket cp",
        "create": "bucket create",
        "download": "job start download",
        "evict": "bucket evict",
        "get": "object get",
        "put": "object put",
        "dsort": "job start dsort",
        "ls": "bucket ls",
        "rmb": "bucket rm",
        "start": "job start",
        "stop": "job stop"
    },
    "default_provider": "ais",
    "no_color": false,
    "verbose": false
}

CLI config can be updated using ais config cli set command or even simply by changing the config file.

The next time you run it CLI will use the updated values.

To get back to system defaults, run ais config cli reset.

Environment variables

First and foremost, there's AIS_ENDPOINT. If defined, it'll take precedence over "cluster.url" (section CLI Config above).

Example:

$ export AIS_ENDPOINT=https://10.07.56.68:51080

In addition, environment can be used to override client-side TLS (aka, HTTPS) configuration - the knobs "client_crt", etc. also listed in the table below:

var name description the corresponding CLI Config
AIS_CRT X509 certificate "cluster.client_crt"
AIS_CRT_KEY X509 certificate's private key "cluster.client_crt_key"
AIS_CLIENT_CA Certificate authority that authorized (signed) the certificate "cluster.client_ca_tls"
AIS_SKIP_VERIFY_CRT true: skip X509 cert verification (usually enabled to circumvent limitations of self-signed certs) "cluster.skip_verify_crt"

First steps

To get the list of supported commands, run:

$ ais help

Alternatively, you could start making use of auto-completions by typing ais and pressing TAB key two times in a row.

To check if the CLI can correctly contact the cluster and to get cluster status, run following command:

$ ais show cluster

Global options

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 variable TERM=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 ls ais://bck --props all --no-color

Backend Provider

The syntax provider://BUCKET_NAME (referred to as BUCKET in help messages) 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 provider
  • aws:// or s3:// - Amazon Web Services
  • azure:// or az:// - Azure Blob Storage
  • gcp:// or gs:// - Google Cloud Storage
  • hdfs:// - HDFS Storage
  • ht:// - HTTP(S) datasets

See also:

Backend Providers Buckets: definition, operations, properties

Verbose errors

CLI uses AIS API to execute operations on a cluster.

Of course, a remote API call - any API call, for that matter - may return errors. For developers, it may be sometimes useful to see a complete and unredacted error information.

Here's an example where we are trying to rename a non-existing bucket:

$ ais bucket mv ais://ddd ais://mmm
Error: bucket "ais://ddd" does not exist

But here's how it'll look once we put CLI in verbose mode:

$ ais config cli set verbose true
"verbose" set to: "true" (was: "false")

$ ais bucket mv ais://ddd ais://mmm
Error: {"tcode":"ErrBckNotFound","message":"bucket \"ais://ddd\" does not exist","method":"HEAD","url_path":"/v1/buckets/ddd","remote_addr":"127.0.0.1:57026","caller":"","node":"p[JFkp8080]","status":404}: HEAD /v1/buckets/ddd (stack: [utils.go:445 <- bucket.go:104 <- bucket_hdlr.go:343])