MinIO Client
Table of Contents
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.
The mc commandline tool is built for compatibility with the AWS S3 API and is tested MinIO and AWS S3 for expected functionality and behavior.
MinIO provides no guarantees for other S3-compatible services, as their S3 API implementation is unknown and therefore unsupported. While mc commands may work as documented, any such usage is at your own risk.
mc
has the following syntax:
mc [GLOBALFLAGS] COMMAND --help
See Command Quick Reference for a list of supported commands.
AGPLv3
mc is AGPLv3 licensed Free and Open Source (FOSS) software.
Applications integrating mc may trigger AGPLv3 compliance requirements. MinIO Commercial Licensing is the best option for applications which trigger AGPLv3 obligations where open-sourcing the application is not an option.
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:
The following commands add a
temporary
extension to your system
PATH for running the
mc
utility. Defer to your operating system
instructions for making permanent modifications to your system PATH.
Alternatively, execute
mc
by navigating to the parent folder and
running
./mc
--help
64-bit Intel
curl https://dl.min.io/client/mc/release/linux-amd64/mc \
--create-dirs \
-o $HOME/minio-binaries/mc
chmod +x $HOME/minio-binaries/mc
export PATH=$PATH:$HOME/minio-binaries/
mc --help
64-bit PPC
curl https://dl.min.io/client/mc/release/linux-ppc64le/mc \
--create-dirs \
-o ~/minio-binaries/mc
chmod +x $HOME/minio-binaries/mc
export PATH=$PATH:$HOME/minio-binaries/
mc --help
ARM64
curl https://dl.min.io/client/mc/release/linux-arm64/mc \
--create-dirs \
-o ~/minio-binaries/mc
chmod +x $HOME/minio-binaries/mc
export PATH=$PATH:$HOME/minio-binaries/
mc --help
brew install minio/stable/mc
mc --help
Open the following file in a browser:
https://dl.min.io/client/mc/release/windows-amd64/mc.exe
Execute the file by double clicking on it, or by running the following in the command prompt or powershell:
\path\to\mc.exe --help
Installation from source is intended for developers and advanced users and requires a working Golang environment. See How to install Golang .
Run the following commands in a terminal environment to install
mc
from source:
go install github.com/minio/mc@latest
mc
update
does not support source-based installations.
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
.
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 requireALIAS
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
andSECRET_KEY
with the access and secret keys for a user on the S3 service.
Replace each argument with the required values. Specifying only the
mc
config
host
add
command starts an input prompt for entering the
required values.
Each of the following tabs contains a provider-specific example:
mc alias set myminio https://minioserver.example.net ACCESS_KEY SECRET KEY
mc alias set myS3 https://s3.amazon.com/endpoint ACCESS_KEY SECRET KEY
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
ortraceroute
). -
The specified
ACCESSKEY
andSECRETKEY
correspond to a user on the S3 service. The user must have permission to perform actions on the service.For MinIO deployments, see 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 |
---|---|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
To remove only the contents of a bucket, use
|
|
The
|
|
The
|
|
The
|
|
Use the
|
|
The
|
|
The
|
|
The MinIO Client
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
|
The
|
Configuration File
mc
uses a
JSON
formatted configuration file used for storing
certain kinds of information, such as the
aliases
for
each configured S3-compatible service.
For Linux and OSX, 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:
-
HOME\.mc\config.json
-
USERPROFILE\.mc\config.json
-
HOMEDRIVE+HOMEPATH\.mc\config.json
You can use the
--config-dir
Global Options
All commands support the following global options:
- --debug
-
Enables verbose output to the console.
For example, the following operation adds verbose output to the
mc ls
command:mc --debug ls play
- --config-dir
-
The path to a
JSON
formatted configuration file that mc uses for storing data. See Configuration File for more information on how mc uses the configuration file.
- --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
- --limit-download
-
Optional
Limit client-side download rates to no more than a specified rate in KiB/s, MiB/s, or GiB/s. This affects only the download to the local device running the MinIO Client. Valid units include:
-
B
for bytes -
K
for kilobytes -
G
for gigabytes -
T
for terabytes -
Ki
for kibibytes -
Gi
for gibibytes -
Ti
for tebibytes
For example, to limit download rates to no more than 1 GiB/s, use the following:
--limit-download 1G
If not specified, MinIO uses an unlimited download rate.
-
- --limit-upload
-
Optional
Limit client-side upload rates to no more than the specified rate in KiB/s, MiB/s, or GiB/s. This affects only the upload from the local device running the MinIO Client. Valid units include:
-
B
for bytes -
K
for kilobytes -
G
for gigabytes -
T
for terabytes -
Ki
for kibibytes -
Gi
for gibibytes -
Ti
for tebibytes
For example, to limit upload rates to no more than 1 GiB/s, use the following:
--limit-upload 1G
If not specified, MinIO uses an unlimited upload rate.
-
- --insecure
-
Disables TLS/SSL certificate verification. Allows TLS connectivity to servers with invalid certificates. Exercise caution when using this option against untrusted S3 hosts.
- --version
-
Displays the current version of
mc
.