CLI reference (nexoctl)

nexoctl is the Nexo command-line client: it manages server aliases, buckets and objects (with any S3-compatible endpoint) and the administration of Nexo through the Admin API.

The complete reference of every command, with syntax, examples and options, is generated from the code of nexoctl and starts at nexoctl. This page summarizes the conventions shared by all the commands.

Command groups

Group	Commands
Buckets and objects	ls, mb, rb, cp, mv, rm, put, pipe, cat, head, stat, find, du, tree, diff, mirror
Sharing and access	share, presign, anonymous, access, cors, dist, cache
Bucket and object settings	version, ilm, event, encrypt, quota, retention, legalhold, tag
Administration	admin: info, user, group, policy, accesskey, config, service, heal, usage, kms, notify, trace, logs, audit, metrics, prometheus, profile, speedtest, lock, cluster
Configuration	alias, completion

Targets

A remote path is written ALIAS[/BUCKET[/PREFIX]], where ALIAS is a name registered with nexoctl alias set; anything else is a local path.

nexoctl alias set local http://localhost:9000 admin supersecret
nexoctl ls local                 # the buckets
nexoctl ls local/photos/2026/    # the objects under a prefix
nexoctl cp report.pdf local/docs/

The aliases, with their credentials, are saved in ~/.nexoctl/config.json (permissions 0600). The private keys generated for the key groups of the distributions are in ~/.nexoctl/keys/<alias>/.

Global options

Option	Effect
--config-dir DIR	configuration directory (default $NEXOCTL_CONFIG_DIR or ~/.nexoctl)
--json	JSON Lines output: one object per line with a status field (success or error), for scripts
-q, --quiet	hides confirmations and progress (results and errors are still printed)
--no-color	disables colors (also with the NO_COLOR variable)
--debug	prints the HTTP requests and responses on stderr, with the secrets redacted
-v, --version	version of nexoctl

Environment variables

Variable	Effect
NEXOCTL_CONFIG_DIR	configuration directory
NEXOCTL_ENC_C	SSE-C keys, ALIAS/BUCKET[/PREFIX]=BASE64KEY, comma-separated (see KMS and SSE)
NO_COLOR	disables colors
SSL_CERT_FILE, SSL_CERT_DIR	trusted CAs for HTTPS servers with a private CA
HTTPS_PROXY, NO_PROXY	HTTP proxy towards the servers

Exit codes

Code	Meaning
0	success
1	generic error (network, server, failed operation)
2	wrong usage: invalid arguments or options
3	resource not found (alias, bucket, object, user, …)
4	access denied (credentials or permissions)
130	interrupted (Ctrl-C)

The codes are part of the CLI contract and do not change between versions.

Command aliases

Many subcommands have a short name, shown in the Aliases section of their page: for example ls for list and rm for remove (nexoctl admin user ls, nexoctl event rm).

Shell completion

nexoctl completion bash > /etc/bash_completion.d/nexoctl     # bash
nexoctl completion zsh  > "${fpath[1]}/_nexoctl"             # zsh
nexoctl completion fish > ~/.config/fish/completions/nexoctl.fish

Generating the documentation

The pages in docs/user/cli are generated by nexoctl itself and must not be edited by hand. They exist in English only (the Italian site shows the English pages). After changing a command:

make docs         # regenerates docs/user/cli (hidden command: nexoctl gendocs DIR)
make docs-check   # fails if the pages in the repository are not up to date (runs in CI)
make docs-site    # complete site in bin/site: MkDocs (--strict, English and Italian) + Admin API reference

make docs-site installs the pinned tools of docs/requirements.txt (MkDocs, Material for MkDocs and mkdocs-static-i18n) in a virtualenv with make docs-tools and, for the Admin API reference, needs Node.js (npx).