CLI overview

AIS CLI is the Swiss‑army knife for managing and monitoring every aspect of an AIStore cluster’s lifecycle — from initial bootstrap to day‑to-day operations, and from single-object I/O to distributed ML workflows.

In addition, CLI provides dataset management commands, performance monitoring, advanced operations, and more.

The entire (diverse and growing) command set is partitioned into top-level namespaces:

1
$ ais <TAB-TAB>
2
3
advanced         cluster          etl              ls               prefetch         search           tls
4
alias            config           evict            ml               put              show             wait
5
archive          cp               get              mpu              remote-cluster   space-cleanup
6
auth             create           help             nbi              rmb              start
7
blob-download    download         job              object           rmo              stop
8
bucket           dsort            log              performance      scrub            storage

CLI namespaces

Hit <TAB> after typing ais  and Bash/Zsh completion reveals namespaces — self‑contained toolboxes such as bucket, cluster, etl, performance, or ml namespace (introduced in v3.30), and so on.

Drill into any namespace with <TAB> and --help to discover its verbs, flags, and usage examples.

ais show

Given an existing AIS instance, maybe the very first command you run would be ais show cluster. For example:

1
$ ais show cluster
2
PROXY            MEM USED(%)     MEM AVAIL       SYS CPU(%)      UPTIME          K8s POD         STATUS
3
p[DlPmJiRU]      0.01%           366.36GiB       1%              526h28m20s      ais-proxy-5     online
4
p[JedAkLgG][P]   0.02%           366.52GiB       2%              526h27m30s      ais-proxy-7     online
5
...
6
7
TARGET         MEM USED(%)  MEM AVAIL  CAP USED(%)   CAP AVAIL   SYS CPU(%)  UPTIME       K8s POD       STATUS
8
t[KoplySra]    0.03%        366.37GiB  52%           8.324TiB    7%          526h26m10s   ais-target-1  online
9
...
10
...
11
12
Summary:
13
   Proxies:             10 (all electable)
14
   Targets:             10 (total disks: 30)
15
   Cluster Map:         version 760, UUID HCGGmT4K0, primary p[JedAkLgG]
16
   Deployment:          K8s
17
   Status:              20 online
18
   Rebalance:           n/a
19
   Authentication:      ...
20
   Version:             ...
21
   Build:               ...

Use --verbose to additionally show LOAD AVERAGE columns.

Press <TAB-TAB> to see all ais show subcommands:

$ ais show <TAB>
auth         cluster          storage          remote-cluster   log        nbi
object       dashboard        rebalance        remote           tls
bucket       performance      config           job              etl

Next, monitoring-wise, you’d maybe run ais show performance, etc.

Table of contents

• Getting Started
• CLI Reference
• CLI Config
• Environment variables
• First steps
• Global options
• Backend Provider
• Verbose errors
• Special keywords
• CLI Help Paging

AIS command-line interface (CLI) is a tool to easily manage and monitor every aspect of the AIS clusters’ lifecycle.

In addition, CLI provides dataset management commands, reading and writing primitives, and more.

Getting Started

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

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

To build with debug, run:

1
$ MODE=debug make cli

Alternatively, install directly from GitHub:

• Install CLI from release binaries

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

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

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

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

• Install CLI autocompletions

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:

• cmd/cli/README.md

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 quickest way to get started with CLI is to type ais and press <TAB-TAB>:

1
$ ais <TAB-TAB>
2
3
advanced         cluster          etl              ls               remote-cluster   space-cleanup
4
alias            config           evict            ml               rmb              start
5
archive          cp               get              object           rmo              stop
6
auth             create           help             performance      scrub            storage
7
blob-download    download         job              prefetch         search           tls
8
bucket           dsort            log              put              show             wait

These are the current set of top-level commands. Each command has its own extended help (the --help option) and, usually, multiple sub-commands (which, in turn, have their respective inline helps and subcommands).

The list of top-level commands provides an overview of the supported functionality and functional grouping. The following is a brief (non-exhaustive and possibly slightly outdated) summary:

Other CLI documentation:

• ais help
• Reference guide
• Monitoring
  • ais show cluster
  • ais show performance
  • ais show job
• Cluster and node management
• Mountpath (disk) management
• Attach, detach, and monitor remote clusters
• Start, stop, and monitor downloads
• Distributed shuffle
• User account and access management
• Jobs

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
• Reset: ais config cli reset
• One‑liner view: ais config cli --json | jq .

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:

1
$ ais config cli --json
2
3
{
4
    "cluster": {
5
        "url": "http://127.0.0.1:8080",
6
        "default_ais_host": "http://127.0.0.1:8080",
7
        "default_docker_host": "http://172.50.0.2:8080",
8
        "client_crt": "",
9
        "client_crt_key": "",
10
        "client_ca_tls": "",
11
        "skip_verify_crt": false
12
    },
13
    "timeout": {
14
        "tcp_timeout": "60s",
15
        "http_timeout": "0s"
16
    },
17
    "auth": {
18
        "url": "http://127.0.0.1:52001"
19
    },
20
    "aliases": {
21
        "dsort": "job start dsort",
22
        "prefetch": "object prefetch",
23
        "rmo": "object rm",
24
        "get": "object get",
25
        "ls": "bucket ls",
26
        "wait": "job wait",
27
        "create": "bucket create",
28
        "download": "job start download",
29
        "start": "job start",
30
        "stop": "job stop",
31
        "blob-download": "job start blob-download",
32
        "cp": "bucket cp",
33
        "evict": "bucket evict",
34
        "put": "object put",
35
        "rmb": "bucket rm"
36
    },
37
    "default_provider": "ais",
38
    "no_color": false,
39
    "verbose": false,
40
    "no_more": false
41
}

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:

1
$ 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:

Further references

• Generating self-signed certificates
• Deploying: 4 targets, 1 gateway, 6 mountpaths, AWS backend
• Accessing HTTPS-based cluster
• Testing with self-signed certificates
• Observability: TLS related alerts
• Updating and reloading X.509 certificates
• Switching cluster between HTTP and HTTPS

First steps

To get the list of supported commands, run:

1
$ 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:

1
$ 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:

1
$ # Correct usage of global and command-specific options.
2
$ ais --no-color ls ais://bck --props all
3
$ ais --no-color ls --props all ais://bck
4
$
5
$ # Incorrect usage of a global option.
6
$ 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
• ht:// - HTTP(S) datasets

See also:

Backend Providers Buckets: design, 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:

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

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

1
$ ais config cli set verbose true
2
"verbose" set to: "true" (was: "false")
3
4
$ ais bucket mv ais://ddd ais://mmm
5
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])

Special keywords

“none” (ref apc.ResetToken) is a broad convention to clear (nullify, reset, empty) config fields - examples include:

1. feature flags
2. log modules (as in: ais config cluster log)
3. backend_bck property of a bucket (see usage/example)
4. slices (a.k.a. multi-value fields) embedded in nested configuration structures (e.g., “auth.required_claims.aud”, “auth.oidc.allowed_iss”, etc.).

and more.

CLI Help Paging

To view help content page-by-page, CLI uses the more command. Disable this by setting no_more to true in your configuration.

1
$ ais config cli set no_more=true
2
"no_more" set to: "true" (was: "false")