> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/aistore/cli/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/aistore/_mcp/server.

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_:

```console
$ ais <TAB-TAB>

advanced         cluster          etl              ls               prefetch         search           tls
alias            config           evict            ml               put              show             wait
archive          cp               get              mpu              remote-cluster   space-cleanup
auth             create           help             nbi              rmb              start
blob-download    download         job              object           rmo              stop
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.

Commands that accept name/value assignments share [assignment and escaping rules](#namevalue-arguments).

### `ais show`

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

```console
$ ais show cluster
PROXY            MEM USED(%)     MEM AVAIL       SYS CPU(%)      UPTIME          K8s POD         STATUS
p[DlPmJiRU]      0.01%           366.36GiB       1%              526h28m20s      ais-proxy-5     online
p[JedAkLgG][P]   0.02%           366.52GiB       2%              526h27m30s      ais-proxy-7     online
...

TARGET         MEM USED(%)  MEM AVAIL  CAP USED(%)   CAP AVAIL   SYS CPU(%)  UPTIME       K8s POD       STATUS
t[KoplySra]    0.03%        366.37GiB  52%           8.324TiB    7%          526h26m10s   ais-target-1  online
...
...

Summary:
   Proxies:             10 (all electable)
   Targets:             10 (total disks: 30)
   Cluster Map:         version 760, UUID HCGGmT4K0, primary p[JedAkLgG]
   Deployment:          K8s
   Status:              20 online
   Rebalance:           n/a
   Authentication:      ...
   Version:             ...
   Build:               ...
```

> Use `--verbose` to additionally show `LOAD AVERAGE` columns.

> Press &lt;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](#getting-started)
- [CLI Reference](#cli-reference)
- [CLI Config](#cli-config)
- [Environment variables](#environment-variables)
- [First steps](#first-steps)
- [Global options](#global-options)
- [Backend Provider](#backend-provider)
- [Verbose errors](#verbose-errors)
- [Special keywords](#special-keywords)
- [Name/value arguments](#namevalue-arguments)
- [CLI Help Paging](#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:

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

To build with debug, run:

```console
$ MODE=debug make cli
```

Alternatively, install directly from GitHub:

* [Install CLI from release binaries](https://github.com/NVIDIA/aistore/blob/main/scripts/install_from_binaries.sh)

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

```console
$ ./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](https://github.com/NVIDIA/aistore/blob/main/cmd/cli/install_autocompletions.sh)

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](#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`](/aistore/cli/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](https://github.com/NVIDIA/aistore/blob/main/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](https://golang.org/doc/code.html#GOPATH).

## CLI Reference

The recommended and quickest way to get started with CLI is to type `ais` and press `<TAB-TAB>`:

```console
$ ais <TAB-TAB>

advanced         cluster          etl              ls               remote-cluster   space-cleanup
alias            config           evict            ml               rmb              start
archive          cp               get              object           rmo              stop
auth             create           help             performance      scrub            storage
blob-download    download         job              prefetch         search           tls
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**:

| Command | Use Case |
|---------|----------|
| [`ais help`](/aistore/cli/help) | All top-level commands and brief descriptions; version and build; general usage guidelines. |
| [`ais advanced`](/aistore/cli/advanced) | Special commands for developers and advanced usage. |
| [`ais alias`](/aistore/cli/alias) | User-defined command aliases. |
| [`ais archive`](/aistore/cli/archive) | Read, write, and list archives (i.e., objects formatted as TAR, TGZ, ZIP, etc.) |
| [`ais auth`](/aistore/cli/auth) | Add/remove/show users, manage user roles, manage access to remote clusters. |
| [`ais blob-download`](/aistore/cli/blob-downloader) | Download a large object or multiple objects from remote storage. |
| [`ais bucket`](/aistore/cli/bucket) | Create/destroy buckets, list bucket's content, show existing buckets and their properties. |
| [`ais cluster`](/aistore/cli/cluster) | Monitor and manage AIS cluster: add/remove nodes, change primary gateway, etc. |
| [`ais config`](/aistore/cli/config) | Set local/global AIS cluster configurations. |
| [`ais etl`](/aistore/cli/etl) | Execute custom transformations on objects. |
| [`ais job`](/aistore/cli/job) | Query and manage jobs (aka eXtended actions or `xactions`). |
| [`ais ml`](/aistore/cli/ml) | Commands that target ML‑centric workflows, including bulk extraction of training samples. |
| [`ais object`](/aistore/cli/object) | PUT and GET (write and read), APPEND, archive, concat, list (buckets, objects), move, evict, promote, ... |
| [`ais search`](/aistore/cli/search) | Search `ais` commands. |
| [`ais show`](/aistore/cli/show) | Monitor anything and everything: performance (all aspects), buckets, jobs, remote clusters and more. |
| [`ais log`](/aistore/cli/log) | Download ais nodes' logs or view the logs in real time. |
| [`ais storage`](/aistore/cli/storage) | Show capacity usage on a per bucket basis (num objects and sizes), attach/detach mountpaths (disks). |
| [`ais performance`](/aistore/cli/performance) | Show performance counters, throughput, latency, disks, used/available capacities. |
| [`ais tls`](/aistore/cli/x509) | Load or reload (an updated) TLS certificate; display information about currently deployed certificates. |
\{: .nobreak\}

Other CLI documentation:

- [`ais help`](/aistore/cli/help)
- [Reference guide](https://github.com/NVIDIA/aistore/blob/main/docs/cli.md#cli-reference)
- [Monitoring](/aistore/cli/show)
  - [`ais show cluster`](/aistore/cli/show)
  - [`ais show performance`](/aistore/cli/show)
  - [`ais show job`](/aistore/cli/show)
- [Cluster and node management](/aistore/cli/cluster)
- [Mountpath (disk) management](/aistore/cli/storage)
- [Attach, detach, and monitor remote clusters](/aistore/cli/cluster)
- [Start, stop, and monitor downloads](/aistore/cli/download)
- [Distributed shuffle](/aistore/cli/dsort)
- [User account and access management](/aistore/cli/auth)
- [Jobs](/aistore/cli/job)

> 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`](https://github.com/NVIDIA/aistore/blob/main/cmn/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:

```json
$ 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": {
        "dsort": "job start dsort",
        "prefetch": "object prefetch",
        "rmo": "object rm",
        "get": "object get",
        "ls": "bucket ls",
        "wait": "job wait",
        "create": "bucket create",
        "download": "job start download",
        "start": "job start",
        "stop": "job stop",
        "blob-download": "job start blob-download",
        "cp": "bucket cp",
        "evict": "bucket evict",
        "put": "object put",
        "rmb": "bucket rm"
    },
    "default_provider": "ais",
    "no_color": false,
    "verbose": false,
    "no_more": 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](#cli-config) above).

Example:

```console
$ 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 | Overrides `cli.json` field | The corresponding [CLI Config](#cli-config) |
| -- | -- | -- |
| `AIS_ENDPOINT`        | `cluster.url`              |
| `AIS_CRT`             | X.509 certificate | "cluster.client_crt" |
| `AIS_CRT_KEY`         | X.509 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 X.509 cert verification (usually enabled to circumvent limitations of self-signed certs) | "cluster.skip_verify_crt" |

### Further references

- [Generating self-signed certificates](/aistore/https#generating-self-signed-certificates)
- [Deploying: 4 targets, 1 gateway, 6 mountpaths, AWS backend](/aistore/https#deploying-4-targets-1-gateway-6-mountpaths-aws-backend)
- [Accessing HTTPS-based cluster](/aistore/https#accessing-https-based-cluster)
- [Testing with self-signed certificates](/aistore/https#testing-with-self-signed-certificates)
- [Observability: TLS related alerts](/aistore/https#observability-tls-related-alerts)
- [Updating and reloading X.509 certificates](/aistore/https#updating-and-reloading-x509-certificates)
- [Switching cluster between HTTP and HTTPS](/aistore/switch_https)

## First steps

To get the list of supported commands, run:

```console
$ 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:

```console
$ 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:

```console
$ # 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

See also:

> [Backend Providers](/aistore/providers)
> [Buckets: design, operations, properties](/aistore/bucket)

## Verbose errors

CLI uses [AIS API](https://github.com/NVIDIA/aistore/tree/main/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:

```console
$ 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:

```console
$ 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])
```

## Special keywords

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

1. [feature flags](/aistore/feature_flags)
2. log modules (as in: `ais config cluster log`)
3. `backend_bck` property of a bucket (see [usage/example](/aistore/bucket))
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.

## Name/value arguments

Commands that set cluster, node, or CLI configuration, bucket properties, object custom
metadata, mountpaths, remote-cluster aliases, or target placement weights share the
same name/value syntax.

### Assignment forms

The following are equivalent:

```console
ais config cluster log.level=4
ais config cluster log.level 4
ais config cluster log.level= 4
ais config cluster log.level =4
ais config cluster log.level = 4
ais config cluster "log.level = 4"
```

Whitespace around `=` is ignored. Separate assignments with whitespace; forms can be
mixed within one command:

```console
ais config cluster log.level=4 space.highwm 90 checksum.type = md5
ais bucket props set ais://bucket mirror.enabled=true mirror.copies 2 checksum.type=md5
```

Commas are part of a value, as in `log.modules=ec,xs`; they do not separate
assignments.

### Quoting and spaces

The shell removes quotes and keeps each quoted string together as one argument, so
names and values may contain spaces. Quote the value, the name, or the entire
assignment:

```console
ais bucket props set ais://bucket extra.custom="owner: team-a; project: research"
ais object set-custom ais://bucket/obj "display name"="two words" owner=team-a
ais object set-custom ais://bucket/obj "display name" "two words"
ais object set-custom ais://bucket/obj "display name = two words"
```

All three `set-custom` commands store the name `display name` with the value
`two words`.

### Values containing `=`

The first unescaped `=` separates the name and value. Additional `=` characters in
the value are literal:

```console
ais object set-custom ais://bucket/obj query="a=1&b=2"
ais object set-custom ais://bucket/obj query "a=1&b=2"
ais cluster remote-attach remais=https://remais.example.com:51080
```

To include `=` in a name, escape it with a backslash:

```console
ais object set-custom ais://bucket/obj 'name\=with\ spaces=value\=with\ spaces'
```

This stores the name `name=with spaces` and value `value=with spaces`. The parser
recognizes `\=`, backslash followed by whitespace, and `\\` (a literal backslash).
Other backslash sequences are retained. Escaped whitespace at the beginning or end
of a name or value is retained; unescaped boundary whitespace is ignored.

Use single quotes to keep these backslashes from being consumed by the shell, or
escape the backslashes themselves. Shell quoting alone cannot protect `=` in a name:
`'name=value'` still reaches the CLI as an assignment.

Object-metadata HEAD responses currently use unescaped `key=value` headers, so
metadata names containing `=` cannot be read back faithfully through HEAD. Use
spaces in metadata names and keep literal `=` in their values until that format
supports escaping; CLI parsing does not change the response format.

### Empty values

Use an empty value to clear a property that supports resetting:

```console
ais bucket props set s3://bucket extra.aws.endpoint=
ais bucket props set s3://bucket extra.aws.endpoint ""
ais bucket props set s3://bucket extra.aws.endpoint="" checksum.type=md5
```

`name= other=value` means an empty `name` value followed by a second assignment.
For a single value containing `=`, use `name other=value`, `name = other=value`, or
escape that `=` when continuing after `name=`. To reset a value before another
space-separated pair, use an explicit empty argument: `name "" other value`.

Configuration and bucket-property commands treat a known property assignment that
follows a bare name as a missing value: `checksum.type mirror.enabled=true` reports
a missing `checksum.type` value. To store such text literally, keep it in the same
argument as its name: `extra.custom=checksum.type=md5`.

### List values

Feature flags, log modules, and bucket access permissions accept several members.
Separate members with commas or whitespace within one argument, or pass them as
separate arguments:

```console
ais config cluster log.modules="ec xs"
ais config cluster log.modules=ec,xs
ais config cluster log.modules ec xs log.level=4
ais config cluster features="S3-API-via-Root Disable-Cold-GET"
ais bucket props set ais://bucket access="GET PUT HEAD-OBJECT" checksum.type=md5
ais bucket props set ais://bucket access GET PUT checksum.type md5
```

Use `none` to reset a list:

```console
ais config cluster log.modules=none
ais config cluster features=none
```

When members are separate arguments, the list ends at the next property name.
Configuration and bucket-property commands reject any other argument that is not a
member of the list, e.g. `invalid access value "HEAD"`.

### Assignments in a flag

A flag such as `--props` takes several assignments in one string. The string is
split at unescaped whitespace, so escape spaces that belong to a value; JSON values
are kept whole:

```console
ais bucket create ais://bucket --props "checksum.type=md5 mirror.enabled=true mirror.copies=2"
ais bucket create ais://bucket --props 'checksum.type = md5 extra.custom=owner:\ team-a'
ais bucket create ais://bucket --props 'extra.custom={"team": "a b"} checksum.type=md5'
```

### JSON

Bucket-property and object-metadata commands also accept a single JSON object
instead of name/value pairs:

```console
ais bucket props set ais://bucket '{"mirror":{"enabled":true,"copies":2},"checksum":{"type":"md5"}}'
ais bucket create ais://bucket --props '{"checksum":{"type":"md5"}}'
ais object set-custom ais://bucket/obj '{"owner":"team-a","query":"a=1&b=2"}'
```

Cluster configuration accepts JSON values for a section or sub-section. The name is
a path, and the JSON value is applied at that path:

```console
ais config cluster checksum='{"type":"md5","validate_warm_get":true}'
ais config cluster space '{"highwm":92,"lowwm":80}'
ais config cluster net.http='{"idle_conns":64}'
```

When JSON paths overlap, the more specific path overrides its enclosing section, regardless of argument order.

Leaf names take plain values: `checksum.type=md5`, not `checksum.type='{"type":"md5"}'`.
JSON and plain values cannot be mixed in one command. Node configuration accepts
plain values only.

Elsewhere, a JSON value is opaque: its quotes and backslashes are preserved as is.
For example, the following stores the JSON text verbatim as object metadata:

```console
ais object set-custom ais://bucket/obj labels='{"team":"a b","tier":"hot"}'
```

### Placement weights, mountpaths, remote clusters

The same forms apply to node IDs and aliases. Quote node IDs, since `[...]` is a
glob pattern in most shells:

```console
ais cluster placement set-weights 't[abc]=3' 't[def]' 1 rest=2
ais storage mountpath attach 't[abc]=/mnt/disk1'
ais storage mountpath attach 't[abc]' /mnt/disk1 't[def]=/mnt/disk2'
ais cluster remote-attach remais https://remais.example.com:51080
```

Placement weights are scalar: each target takes exactly one value.

## 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.

```console
$ ais config cli set no_more=true
"no_more" set to: "true" (was: "false")
```