docs/source/reference/minio-mc.rst

MinIO Client

minio

Table of Contents

• Introduction to the MinIO Client (MC) Commands
• Installing and Running MinIO on Linux

mc

The MinIO Client mc command line tool provides a modern alternative to UNIX commands like ls, cat, cp, mirror, and diff with support for both filesystems and Amazon S3-compatible cloud storage services.

mc has the following syntax:

mc [GLOBALFLAGS] COMMAND --help

See minio-mc-commands for a list of supported commands.

Version Alignment with MinIO Server

The MinIO Client releases separately from the MinIO Server.

For best functionality and compatibility, use a MinIO Client version released closely to your MinIO Server version. For example, a MinIO Client released the same day or later than your MinIO Server version.

You can install a version of the MinIO Client that is more recent than the MinIO Server version. However, if the MinIO Client version skews too far from the MinIO Server version, you may see increased warnings or errors as a result of the differences. For example, while core S3 APIs around copying (mc cp) may remain unchanged, some features or flags may only be available or stable if the client and server versions are aligned.

Quickstart

1) Install mc

Install the mc command line tool onto the host machine. Click the tab that corresponds to the host machine operating system or environment:

2) Create an Alias for the S3-Compatible Service

Important

The following example temporarily disables the bash history to mitigate the risk of authentication credentials leaking in plain text. This is a basic security measure and does not mitigate all possible attack vectors. Defer to security best practices for your operating system for inputting sensitive information on the command line.

Use the mc alias set command to add an Amazon S3-compatible service to the mc configuration <mc-configuration>.

bash +o history
mc alias set ALIAS HOSTNAME ACCESS_KEY SECRET_KEY
bash -o history

• Replace ALIAS with a name to associate to the S3 service. mc commands typically require ALIAS as an argument for identifying which S3 service to execute against.
• Replace HOSTNAME with the URL endpoint or IP address of the S3 service.
• Replace ACCESS_KEY and SECRET_KEY with the access and secret keys for a user on the S3 service.

Replace each argument with the required values. If you omit the ACCESS_KEY and SECRET_KEY, the command prompts you to enter those values in the CLI.

Each of the following tabs contains a provider-specific example:

MinIO Server

mc alias set myminio https://minioserver.example.net ACCESS_KEY SECRET_KEY

AWS S3 Storage

mc alias set myS3 https://s3.{your-region-code}.amazonaws.com/endpoint ACCESS_KEY SECRET_KEY

Google Cloud Storage

mc alias set myGCS https://storage.googleapis.com/endpoint ACCESS_KEY SECRET_KEY

3) Test the Connection

Use the mc admin info command to test the connection to the newly added MinIO deployment:

mc admin info myminio

The command returns information on the S3 service if successful. If unsuccessful, check each of the following:

• The host machine has connectivity to the S3 service URL (i.e. using ping or traceroute).

• The specified ACCESSKEY and SECRETKEY correspond to a user on the S3 service. The user must have permission to perform actions on the service.

  For MinIO deployments, see minio-access-management for more information on user access permissions. For other S3-compatible services, defer to the documentation for that service.

Command Quick Reference

The following table lists mc commands:

Note

The MinIO Client also includes an administration extension for managing MinIO deployments. See mc admin for more complete documentation.

The below table does not include those commands.

Command	Description
mc alias list mc alias remove mc alias set mc alias import mc alias export
mc anonymous get mc anonymous get-json mc anonymous links mc anonymous list mc anonymous set mc anonymous set-json
mc batch describe mc batch generate mc batch list mc batch start mc batch status
mc cat
mc cp
mc diff
mc du
mc encrypt clear mc encrypt info mc encrypt set
mc event add mc event ls mc event rm
mc find
mc get
mc head
mc idp ldap accesskey mc idp ldap accesskey create-with-login mc idp ldap add mc idp ldap disable mc idp ldap enable mc idp ldap info mc idp ldap ls mc idp ldap policy mc idp ldap rm mc idp ldap update
mc idp openid add mc idp openid disable mc idp openid enable mc idp openid info mc idp openid ls mc idp openid rm mc idp openid update
mc idp ldap policy attach mc idp ldap policy detach mc idp ldap policy entities
mc ilm restore mc ilm rule add mc ilm rule edit mc ilm rule export mc ilm rule import mc ilm rule ls mc ilm rule rm mc ilm tier add mc ilm tier check mc ilm tier info mc ilm tier ls mc ilm tier rm mc ilm tier update
mc legalhold clear mc legalhold info mc legalhold set
mc license info mc license register mc license update
mc ls
mc mb
mc mirror
mc mv
mc od
mc ping
mc pipe
mc put
mc rb
mc ready
mc replicate add mc replicate backlog mc replicate export mc replicate import mc replicate ls mc replicate resync mc replicate rm mc replicate status mc replicate update
mc retention clear mc retention info mc retention set
mc rm
mc share download mc share ls mc share upload
mc sql
mc stat
mc support callhome mc support diag mc support inspect mc support perf mc support profile mc support proxy mc support top api mc support top disk mc support top locks mc support upload
mc tag list mc tag remove mc tag set
mc tree
mc undo
mc update
mc version enable mc version info mc version suspend
mc watch

Configuration File

mc uses a JSON formatted configuration file used for storing certain kinds of information, such as the aliases <mc alias> for each configured S3-compatible service.

For Linux and macOS, the default configuration file location is ~/.mc/config.json.

For Windows, mc attempts to construct a default file path by trying specific environment variables. If a variable is unset, mc moves to the next variable. If all attempts fail, mc returns an error. The following list describes each possible file path location in the order mc checks them:

1. HOME\.mc\config.json
2. USERPROFILE\.mc\config.json
3. HOMEDRIVE+HOMEPATH\.mc\config.json

You can use the --config-dir

Certificates

The MinIO Client stores certificates and CAs for deployments to the following paths:

Linux, macOS, and other Unix-like systems:

~/.mc/certs/ # certificates
~/.mc/certs/CAs/ # Certificate Authorities

Windows systems:

C:\Users\[username]\mc\certs\ # certificates
C:\Users\[username]\mc\certs\CAs\ # Certificate Authorities

When creating a new alias <minio-mc-alias>, the MinIO Client fetches the peer certificate, computes the public key fingerprint, and asks the user whether to accept the deployment's certificate. If you decide to trust the certificate, the MinIO Client adds the certificate to the certificate authority path listed above.

Note

In testing environments, you can bypass the certificate check for selected MinIO Client commands by passing the --insecure flag.

Pattern Matching

Some commands and flags allow for pattern matching. When enabled, a pattern can include either of these wildcards for character replacement:

• * to represent a string of characters to match, either in the middle or end.
• ? to represent a single character.

For example, refer to the following examples for wildcard uses and their results.

Pattern	Text	Match Result
abc*	ab	Match
abc*	abd	Not a match
abc*c	abcd	Match
ab*??d	abxxc	Match
ab*??d	abxc	Match
ab??d	abxc	Match
ab??d	abc	Match
ab??d	abcxdd	Not a match

Global Options

mc

All commands <minio-mc-commands> support the following global options. You can also define some of these options using Environment Variables <minio-server-envvar-mc>.

--config-dir

The path to a JSON formatted configuration file that mc uses for storing data. See mc-configuration for more information on how mc uses the configuration file.

Alternatively, set the environment variable MC_CONFIG_DIR.

--debug

Enables verbose output to the console.

For example, the following operation adds verbose output to the mc ls command:

mc --debug ls play

Alternatively, set the environment variable MC_DEBUG.

--disable-pager, --dp

mc RELEASE.2024-04-29T09-56-05Z

Disable the pager functionality of the MinIO Client in the CLI. When used, output prints to raw STDOUT instead.

--insecure

Disables TLS/SSL certificate verification. Allows TLS connectivity to servers with invalid certificates. Exercise caution when using this option against untrusted S3 hosts.

Alternatively, set the environment variable MC_INSECURE.

--json

Enables JSON lines formatted output to the console.

For example, the following operation adds JSON Lines output to the mc ls command:

mc --json ls play 

Alternatively, set the environment variable MC_JSON.

--no-color

Disables the built-in color theme for console output. Useful for dumb terminals.

Alternatively, set the environment variable MC_NO_COLOR.

--quiet

Suppresses console output.

Alternatively, set the environment variable MC_QUIET.

--resolve

mc RELEASE.2024-08-13T05-33-17Z

Creates a custom DNS mapping to resolve a HOST to a specified IP address.

Use the following syntax:

--resolve HOST[:PORT]=IP 

For example:

mc alias set --resolve myminio.example.com:9000=192.168.188.118 'myminio' 'https://myminio.example.com:9000' 'miniouser' 'miniosecret'

Repeat the flag multiple times to add additional custom DNS mappings.

--version

Displays the current version of mc.

--help

Displays a summary of command usage on the terminal.

/reference/minio-mc/minio-client-settings /reference/minio-mc/mc-alias /reference/minio-mc/mc-anonymous /reference/minio-mc/mc-batch /reference/minio-mc/mc-cat /reference/minio-mc/mc-cp /reference/minio-mc/mc-diff /reference/minio-mc/mc-du /reference/minio-mc/mc-encrypt /reference/minio-mc/mc-event /reference/minio-mc/mc-find /reference/minio-mc/mc-get /reference/minio-mc/mc-head /reference/minio-mc/mc-idp-ldap /reference/minio-mc/mc-idp-ldap-accesskey /reference/minio-mc/mc-idp-ldap-accesskey-create-with-login /reference/minio-mc/mc-idp-ldap-policy /reference/minio-mc/mc-idp-openid /reference/minio-mc/mc-ilm /reference/minio-mc/mc-legalhold /reference/minio-mc/mc-license /reference/minio-mc/mc-ls /reference/minio-mc/mc-mb /reference/minio-mc/mc-mirror /reference/minio-mc/mc-mv /reference/minio-mc/mc-od /reference/minio-mc/mc-ping /reference/minio-mc/mc-pipe /reference/minio-mc/mc-put /reference/minio-mc/mc-rb /reference/minio-mc/mc-ready /reference/minio-mc/mc-replicate /reference/minio-mc/mc-retention /reference/minio-mc/mc-rm /reference/minio-mc/mc-share /reference/minio-mc/mc-sql /reference/minio-mc/mc-stat /reference/minio-mc/mc-support /reference/minio-mc/mc-tag /reference/minio-mc/mc-tree /reference/minio-mc/mc-undo /reference/minio-mc/mc-update /reference/minio-mc/mc-version /reference/minio-mc/mc-watch