docs/source/reference/minio-mc.rst

MinIO Client

minio

Table of Contents

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.

AGPLv3

mc is AGPLv3 <mc/blob/master/LICENSE> 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:

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

MinIO Server

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

AWS S3 Storage

mc alias set myS3 https://s3.amazon.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:

Command	Description
mc alias set mc alias remove mc alias list	The mc alias commands provide a convenient interface for managing the list of S3-compatible hosts that mc can connect to and run operations against. mc commands that operate on S3-compatible services require specifying an alias for that service.
mc anonymous set mc anonymous set-json mc anonymous get mc anonymous get-json mc anonymous list mc anonymous links	The mc anonymous command supports setting or removing anonymous policies <minio-policy> to a bucket and its contents. Buckets with anonymous policies allow public access where clients can perform any action granted by the policy without authentication <minio-authentication-and-identity-management>.
mc batch generate mc batch start mc batch list mc batch status mc batch describe	The mc batch commands allow you to run one or more job tasks on a MinIO deployment. Specify the jobs to run in a YAML-formatted file you can start generating with mc batch generate. Use mc batch start to when you are ready to begin the job(s) defined in the file. Display current jobs with mc batch list, see current status with mc batch status, and output the full definition for a current job with mc batch describe.
mc cat
mc cp
mc diff
mc encrypt set mc encrypt info mc encrypt clear	The mc encrypt command sets, updates, or disables the default bucket Server-Side Encryption (SSE) mode. MinIO automatically encrypts objects using the specified SSE mode.
mc event add mc event remove mc event list	The mc event command supports adding, removing, and listing the bucket event notifications. MinIO automatically sends triggered events to the configured notification targets. MinIO supports notification targets like AMQP (RabbitMQ), Redis, ElasticSearch, NATS and PostgreSQL. See MinIO Bucket Notifications <minio-bucket-notifications> for more information.
mc find
mc head
mc ilm add mc ilm ls mc ilm edit mc ilm rm mc ilm export mc ilm import	The mc ilm command supports managing object lifecycle management rules <minio-lifecycle-management> on a MinIO deployment. Use this command to set both minio-lifecycle-management-tiering and minio-lifecycle-management-expiration rules on a bucket.
mc legalhold set mc legalhold info mc legalhold clear	The mc legalhold command sets, removes, or retrieves the Object Legal Hold (WORM) <minio-object-locking-legalhold> settings for object(s).
mc license register mc license info mc license update mc license unregister	The mc license commands work with cluster registration for . Use the commands to register a deployment, unregister a deployment, display information about the cluster's current license, or update the license key for a cluster.
mc ls
mc mb
mc mirror
mc mv
mc od
mc pipe
mc rb
mc retention set mc retention info mc retention clear	The mc retention command configures the Write-Once Read-Many (WORM) locking <minio-object-locking> settings for an object or object(s) in a bucket. You can also set the default object lock settings for a bucket, where all objects without explicit object lock settings inherit the bucket default.
mc replicate add mc replicate diff mc replicate export mc replicate import mc replicate ls mc replicate resync mc replicate rm mc replicate status mc replicate update	The mc replicate <mc replicate add> command configures and manages the Server-Side Bucket Replication <minio-bucket-replication-serverside> for a MinIO deployment, including active-active replication configurations <minio-bucket-replication-serverside-twoway> and resynchronization <minio-replication-behavior-resync>.
mc rm
mc share download mc share upload mc share list	The mc share download and mc share upload commands generate presigned URLs for downloading and uploading objects to a MinIO bucket.
mc sql
mc stat
mc support diag mc support inspect mc support perf mc support profile mc support top	The MinIO Client mc support commands provides tools for analyzing deployment health or performance and for running diagnostics. You can also upload generated health reports for further analysis by MinIO engineering.
mc tag set mc tag remove mc tag list	The mc tag command adds, removes, and lists tags associated to a bucket or object.
mc tree
mc undo
mc update
mc version
mc watch

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

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

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

You can use the --config-dir

Global Options

mc

All commands <minio-mc-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 mc-configuration 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 

--no-color

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

--quiet

Suppresses console output.

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

--help

Displays a summary of command usage on the terminal.

/reference/minio-mc/mc-alias-set /reference/minio-mc/mc-alias-list /reference/minio-mc/mc-alias-remove /reference/minio-mc/mc-anonymous-set /reference/minio-mc/mc-anonymous-get /reference/minio-mc/mc-anonymous-list /reference/minio-mc/mc-anonymous-links /reference/minio-mc/mc-anonymous-get-json /reference/minio-mc/mc-anonymous-set-json /reference/minio-mc/mc-batch-describe /reference/minio-mc/mc-batch-generate /reference/minio-mc/mc-batch-list /reference/minio-mc/mc-batch-start /reference/minio-mc/mc-batch-status /reference/minio-mc/mc-cat /reference/minio-mc/mc-cp /reference/minio-mc/mc-diff /reference/minio-mc/mc-encrypt-set /reference/minio-mc/mc-encrypt-info /reference/minio-mc/mc-encrypt-clear /reference/minio-mc/mc-event-add /reference/minio-mc/mc-event-list /reference/minio-mc/mc-event-remove /reference/minio-mc/mc-find /reference/minio-mc/mc-head /reference/minio-mc/mc-ilm-add /reference/minio-mc/mc-ilm-edit /reference/minio-mc/mc-ilm-ls /reference/minio-mc/mc-ilm-restore /reference/minio-mc/mc-ilm-rm /reference/minio-mc/mc-ilm-export /reference/minio-mc/mc-ilm-import /reference/minio-mc/mc-legalhold-set /reference/minio-mc/mc-legalhold-info /reference/minio-mc/mc-legalhold-clear /reference/minio-mc/mc-license-info /reference/minio-mc/mc-license-register /reference/minio-mc/mc-license-unregister /reference/minio-mc/mc-license-update /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-pipe /reference/minio-mc/mc-rb /reference/minio-mc/mc-replicate-add /reference/minio-mc/mc-replicate-diff /reference/minio-mc/mc-replicate-ls /reference/minio-mc/mc-replicate-update /reference/minio-mc/mc-replicate-resync /reference/minio-mc/mc-replicate-rm /reference/minio-mc/mc-replicate-status /reference/minio-mc/mc-replicate-export /reference/minio-mc/mc-replicate-import /reference/minio-mc/mc-retention-set /reference/minio-mc/mc-retention-info /reference/minio-mc/mc-retention-clear /reference/minio-mc/mc-rm /reference/minio-mc/mc-share-download /reference/minio-mc/mc-share-upload /reference/minio-mc/mc-share-list /reference/minio-mc/mc-sql /reference/minio-mc/mc-stat /reference/minio-mc/mc-support-diag /reference/minio-mc/mc-support-inspect /reference/minio-mc/mc-support-logs-disable /reference/minio-mc/mc-support-logs-enable /reference/minio-mc/mc-support-logs-show /reference/minio-mc/mc-support-logs-status /reference/minio-mc/mc-support-perf /reference/minio-mc/mc-support-profile /reference/minio-mc/mc-support-top /reference/minio-mc/mc-tag-set /reference/minio-mc/mc-tag-list /reference/minio-mc/mc-tag-remove /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