1# MinIO Client Quickstart Guide 2[](https://slack.min.io) [](https://goreportcard.com/report/minio/mc) [](https://hub.docker.com/r/minio/mc/) [](https://github.com/minio/mc/blob/master/LICENSE) 3 4MinIO Client (mc) provides a modern alternative to UNIX commands like ls, cat, cp, mirror, diff, find etc. It supports filesystems and Amazon S3 compatible cloud storage service (AWS Signature v2 and v4). 5 6``` 7alias set, remove and list aliases in configuration file 8ls list buckets and objects 9mb make a bucket 10rb remove a bucket 11cp copy objects 12mirror synchronize object(s) to a remote site 13cat display object contents 14head display first 'n' lines of an object 15pipe stream STDIN to an object 16share generate URL for temporary access to an object 17find search for objects 18sql run sql queries on objects 19stat show object metadata 20mv move objects 21tree list buckets and objects in a tree format 22du summarize disk usage recursively 23retention set retention for object(s) 24legalhold set legal hold for object(s) 25diff list differences in object name, size, and date between two buckets 26rm remove objects 27encrypt manage bucket encryption config 28event manage object notifications 29watch listen for object notification events 30undo undo PUT/DELETE operations 31policy manage anonymous access to buckets and objects 32tag manage tags for bucket(s) and object(s) 33ilm manage bucket lifecycle 34version manage bucket versioning 35replicate configure server side bucket replication 36admin manage MinIO servers 37update update mc to latest release 38``` 39 40## Docker Container 41### Stable 42``` 43docker pull minio/mc 44docker run minio/mc ls play 45``` 46 47### Edge 48``` 49docker pull minio/mc:edge 50docker run minio/mc:edge ls play 51``` 52 53**Note:** Above examples run `mc` against MinIO [_play_ environment](#test-your-setup) by default. To run `mc` against other S3 compatible servers, start the container this way: 54 55``` 56docker run -it --entrypoint=/bin/sh minio/mc 57``` 58 59then use the [`mc config` command](#add-a-cloud-storage-service). 60 61### GitLab CI 62When using the Docker container in GitLab CI, you must [set the entrypoint to an empty string](https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#overriding-the-entrypoint-of-an-image). 63 64``` 65deploy: 66 image: 67 name: minio/mc 68 entrypoint: [''] 69 stage: deploy 70 before_script: 71 - mc alias set minio $MINIO_HOST $MINIO_ACCESS_KEY $MINIO_SECRET_KEY 72 script: 73 - mc cp <source> <destination> 74``` 75 76## macOS 77### Homebrew 78Install mc packages using [Homebrew](http://brew.sh/) 79 80``` 81brew install minio/stable/mc 82mc --help 83``` 84 85## GNU/Linux 86### Binary Download 87| Platform | Architecture | URL | 88| ---------- | -------- |------| 89|GNU/Linux|64-bit Intel|https://dl.min.io/client/mc/release/linux-amd64/mc | 90||64-bit PPC|https://dl.min.io/client/mc/release/linux-ppc64le/mc | 91 92``` 93wget https://dl.min.io/client/mc/release/linux-amd64/mc 94chmod +x mc 95./mc --help 96``` 97 98## Microsoft Windows 99### Binary Download 100| Platform | Architecture | URL | 101| ---------- | -------- |------| 102|Microsoft Windows|64-bit Intel|https://dl.min.io/client/mc/release/windows-amd64/mc.exe | 103 104``` 105mc.exe --help 106``` 107 108## Install from Source 109Source installation is only intended for developers and advanced users. If you do not have a working Golang environment, please follow [How to install Golang](https://golang.org/doc/install). Minimum version required is [go1.17](https://golang.org/dl/#stable) 110 111```sh 112go install github.com/minio/mc@latest 113``` 114 115## Add a Cloud Storage Service 116If you are planning to use `mc` only on POSIX compatible filesystems, you may skip this step and proceed to [everyday use](#everyday-use). 117 118To add one or more Amazon S3 compatible hosts, please follow the instructions below. `mc` stores all its configuration information in ``~/.mc/config.json`` file. 119 120``` 121mc alias set <ALIAS> <YOUR-S3-ENDPOINT> <YOUR-ACCESS-KEY> <YOUR-SECRET-KEY> --api <API-SIGNATURE> --path <BUCKET-LOOKUP-TYPE> 122``` 123 124`<ALIAS>` is simply a short name to your cloud storage service. S3 end-point, access and secret keys are supplied by your cloud storage provider. API signature is an optional argument. By default, it is set to "S3v4". 125 126Path is an optional argument. It is used to indicate whether dns or path style url requests are supported by the server. It accepts "on", "off" as valid values to enable/disable path style requests.. By default, it is set to "auto" and SDK automatically determines the type of url lookup to use. 127 128### Example - MinIO Cloud Storage 129MinIO server startup banner displays URL, access and secret keys. 130 131``` 132mc alias set minio http://192.168.1.51 BKIKJAA5BMMU2RHO6IBB V7f1CwQqAcwo80UEIJEjc5gVQUSSx5ohQ9GSrr12 133``` 134 135### Example - Amazon S3 Cloud Storage 136Get your AccessKeyID and SecretAccessKey by following [AWS Credentials Guide](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html). 137 138``` 139mc alias set s3 https://s3.amazonaws.com BKIKJAA5BMMU2RHO6IBB V7f1CwQqAcwo80UEIJEjc5gVQUSSx5ohQ9GSrr12 140``` 141 142**Note**: As an IAM user on Amazon S3 you need to make sure the user has full access to the buckets or set the following restricted policy for your IAM user 143 144```json 145{ 146 "Version": "2012-10-17", 147 "Statement": [ 148 { 149 "Sid": "AllowBucketStat", 150 "Effect": "Allow", 151 "Action": [ 152 "s3:HeadBucket" 153 ], 154 "Resource": "*" 155 }, 156 { 157 "Sid": "AllowThisBucketOnly", 158 "Effect": "Allow", 159 "Action": "s3:*", 160 "Resource": [ 161 "arn:aws:s3:::<your-restricted-bucket>/*", 162 "arn:aws:s3:::<your-restricted-bucket>" 163 ] 164 } 165 ] 166} 167``` 168 169### Example - Google Cloud Storage 170Get your AccessKeyID and SecretAccessKey by following [Google Credentials Guide](https://cloud.google.com/storage/docs/migrating?hl=en#keys) 171 172``` 173mc alias set gcs https://storage.googleapis.com BKIKJAA5BMMU2RHO6IBB V8f1CwQqAcwo80UEIJEjc5gVQUSSx5ohQ9GSrr12 174``` 175 176## Test Your Setup 177`mc` is pre-configured with https://play.min.io, aliased as "play". It is a hosted MinIO server for testing and development purpose. To test Amazon S3, simply replace "play" with "s3" or the alias you used at the time of setup. 178 179*Example:* 180 181List all buckets from https://play.min.io 182 183``` 184mc ls play 185[2016-03-22 19:47:48 PDT] 0B my-bucketname/ 186[2016-03-22 22:01:07 PDT] 0B mytestbucket/ 187[2016-03-22 20:04:39 PDT] 0B mybucketname/ 188[2016-01-28 17:23:11 PST] 0B newbucket/ 189[2016-03-20 09:08:36 PDT] 0B s3git-test/ 190``` 191 192Make a bucket 193`mb` command creates a new bucket. 194 195*Example:* 196``` 197mc mb play/mybucket 198Bucket created successfully `play/mybucket`. 199``` 200 201Copy Objects 202`cp` command copies data from one or more sources to a target. 203 204*Example:* 205``` 206mc cp myobject.txt play/mybucket 207myobject.txt: 14 B / 14 B ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 100.00 % 41 B/s 0 208``` 209 210## Everyday Use 211 212### Shell aliases 213You may add shell aliases to override your common Unix tools. 214 215``` 216alias ls='mc ls' 217alias cp='mc cp' 218alias cat='mc cat' 219alias mkdir='mc mb' 220alias pipe='mc pipe' 221alias find='mc find' 222``` 223 224### Shell autocompletion 225In case you are using bash, zsh or fish. Shell completion is embedded by default in `mc`, to install auto-completion use `mc --autocompletion`. Restart the shell, mc will auto-complete commands as shown below. 226 227``` 228mc <TAB> 229admin config diff find ls mirror policy session sql update watch 230cat cp event head mb pipe rm share stat version 231``` 232 233## Explore Further 234- [MinIO Client Complete Guide](https://docs.min.io/docs/minio-client-complete-guide) 235- [MinIO Quickstart Guide](https://docs.min.io/docs/minio-quickstart-guide) 236- [The MinIO documentation website](https://docs.min.io) 237 238## Contribute to MinIO Project 239Please follow MinIO [Contributor's Guide](https://github.com/minio/mc/blob/master/CONTRIBUTING.md) 240 241## License 242Use of `mc` is governed by the GNU AGPLv3 license that can be found in the [LICENSE](https://github.com/minio/mc/blob/master/LICENSE) file. 243
){kind=link}