github.com/minio/mc@v0.0.0-20240503112107-b471de8d1882/README.md (about) 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 4 # Documentation 5 - [MC documentation](https://min.io/docs/minio/linux/reference/minio-mc.html) 6 7 MinIO 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). 8 9 ``` 10 alias manage server credentials in configuration file 11 admin manage MinIO servers 12 anonymous manage anonymous access to buckets and objects 13 batch manage batch jobs 14 cp copy objects 15 cat display object contents 16 diff list differences in object name, size, and date between two buckets 17 du summarize disk usage recursively 18 encrypt manage bucket encryption config 19 event manage object notifications 20 find search for objects 21 get get s3 object to local 22 head display first 'n' lines of an object 23 ilm manage bucket lifecycle 24 idp manage MinIO IDentity Provider server configuration 25 license license related commands 26 legalhold manage legal hold for object(s) 27 ls list buckets and objects 28 mb make a bucket 29 mv move objects 30 mirror synchronize object(s) to a remote site 31 od measure single stream upload and download 32 ping perform liveness check 33 pipe stream STDIN to an object 34 put upload an object to a bucket 35 quota manage bucket quota 36 rm remove object(s) 37 retention set retention for object(s) 38 rb remove a bucket 39 replicate configure server side bucket replication 40 ready checks if the cluster is ready or not 41 sql run sql queries on objects 42 stat show object metadata 43 support support related commands 44 share generate URL for temporary access to an object 45 tree list buckets and objects in a tree format 46 tag manage tags for bucket and object(s) 47 undo undo PUT/DELETE operations 48 update update mc to latest release 49 version manage bucket versioning 50 watch listen for object notification events 51 ``` 52 53 ## Docker Container 54 ### Stable 55 ``` 56 docker pull minio/mc 57 docker run minio/mc ls play 58 ``` 59 60 ### Edge 61 ``` 62 docker pull minio/mc:edge 63 docker run minio/mc:edge ls play 64 ``` 65 66 **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: 67 68 ``` 69 docker run -it --entrypoint=/bin/sh minio/mc 70 ``` 71 72 then use the [`mc alias` command](#add-a-cloud-storage-service). 73 74 ### GitLab CI 75 When 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#override-the-entrypoint-of-an-image). 76 77 ``` 78 deploy: 79 image: 80 name: minio/mc 81 entrypoint: [''] 82 stage: deploy 83 before_script: 84 - mc alias set minio $MINIO_HOST $MINIO_ACCESS_KEY $MINIO_SECRET_KEY 85 script: 86 - mc cp <source> <destination> 87 ``` 88 89 ## macOS 90 ### Homebrew 91 Install mc packages using [Homebrew](http://brew.sh/) 92 93 ``` 94 brew install minio/stable/mc 95 mc --help 96 ``` 97 98 ## GNU/Linux 99 ### Binary Download 100 | Platform | Architecture | URL | 101 | ---------- | -------- |------| 102 |GNU/Linux|64-bit Intel|https://dl.min.io/client/mc/release/linux-amd64/mc | 103 |GNU/Linux|64-bit PPC|https://dl.min.io/client/mc/release/linux-ppc64le/mc | 104 |GNU/Linux|64-bit ARM|https://dl.min.io/client/mc/release/linux-arm64/mc | 105 |Linux/s390x|S390X|https://dl.min.io/client/mc/release/linux-s390x/mc | 106 107 ``` 108 wget https://dl.min.io/client/mc/release/linux-amd64/mc 109 chmod +x mc 110 ./mc --help 111 ``` 112 113 ## Microsoft Windows 114 ### Binary Download 115 | Platform | Architecture | URL | 116 | ---------- | -------- |------| 117 |Microsoft Windows|64-bit Intel|https://dl.min.io/client/mc/release/windows-amd64/mc.exe | 118 119 ``` 120 mc.exe --help 121 ``` 122 123 ## Install from Source 124 Source 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) 125 126 ```sh 127 go install github.com/minio/mc@latest 128 ``` 129 130 ## Add a Cloud Storage Service 131 If you are planning to use `mc` only on POSIX compatible filesystems, you may skip this step and proceed to [everyday use](#everyday-use). 132 133 To add one or more Amazon S3 compatible hosts, please follow the instructions below. `mc` stores all its configuration information in ``~/.mc/config.json`` file. 134 135 ``` 136 mc alias set <ALIAS> <YOUR-S3-ENDPOINT> <YOUR-ACCESS-KEY> <YOUR-SECRET-KEY> --api <API-SIGNATURE> --path <BUCKET-LOOKUP-TYPE> 137 ``` 138 139 `<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". 140 141 Path 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. 142 143 ### Example - MinIO Cloud Storage 144 MinIO server startup banner displays URL, access and secret keys. 145 146 ``` 147 mc alias set minio http://192.168.1.51 BKIKJAA5BMMU2RHO6IBB V7f1CwQqAcwo80UEIJEjc5gVQUSSx5ohQ9GSrr12 148 ``` 149 150 ### Example - Amazon S3 Cloud Storage 151 Get your AccessKeyID and SecretAccessKey by following [AWS Credentials Guide](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html). 152 153 ``` 154 mc alias set s3 https://s3.amazonaws.com BKIKJAA5BMMU2RHO6IBB V7f1CwQqAcwo80UEIJEjc5gVQUSSx5ohQ9GSrr12 155 ``` 156 157 **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 158 159 ```json 160 { 161 "Version": "2012-10-17", 162 "Statement": [ 163 { 164 "Sid": "AllowBucketStat", 165 "Effect": "Allow", 166 "Action": [ 167 "s3:HeadBucket" 168 ], 169 "Resource": "*" 170 }, 171 { 172 "Sid": "AllowThisBucketOnly", 173 "Effect": "Allow", 174 "Action": "s3:*", 175 "Resource": [ 176 "arn:aws:s3:::<your-restricted-bucket>/*", 177 "arn:aws:s3:::<your-restricted-bucket>" 178 ] 179 } 180 ] 181 } 182 ``` 183 184 ### Example - Google Cloud Storage 185 Get your AccessKeyID and SecretAccessKey by following [Google Credentials Guide](https://cloud.google.com/storage/docs/migrating?hl=en#keys) 186 187 ``` 188 mc alias set gcs https://storage.googleapis.com BKIKJAA5BMMU2RHO6IBB V8f1CwQqAcwo80UEIJEjc5gVQUSSx5ohQ9GSrr12 189 ``` 190 191 ## Test Your Setup 192 `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. 193 194 *Example:* 195 196 List all buckets from https://play.min.io 197 198 ``` 199 mc ls play 200 [2016-03-22 19:47:48 PDT] 0B my-bucketname/ 201 [2016-03-22 22:01:07 PDT] 0B mytestbucket/ 202 [2016-03-22 20:04:39 PDT] 0B mybucketname/ 203 [2016-01-28 17:23:11 PST] 0B newbucket/ 204 [2016-03-20 09:08:36 PDT] 0B s3git-test/ 205 ``` 206 207 Make a bucket 208 `mb` command creates a new bucket. 209 210 *Example:* 211 ``` 212 mc mb play/mybucket 213 Bucket created successfully `play/mybucket`. 214 ``` 215 216 Copy Objects 217 `cp` command copies data from one or more sources to a target. 218 219 *Example:* 220 ``` 221 mc cp myobject.txt play/mybucket 222 myobject.txt: 14 B / 14 B ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 100.00 % 41 B/s 0 223 ``` 224 225 ## Everyday Use 226 227 ### Shell aliases 228 You may add shell aliases to override your common Unix tools. 229 230 ``` 231 alias ls='mc ls' 232 alias cp='mc cp' 233 alias cat='mc cat' 234 alias mkdir='mc mb' 235 alias pipe='mc pipe' 236 alias find='mc find' 237 ``` 238 239 ### Shell autocompletion 240 In 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. 241 242 ``` 243 mc <TAB> 244 admin config diff find ls mirror policy session sql update watch 245 cat cp event head mb pipe rm share stat version 246 ``` 247 248 ## Contribute to MinIO Project 249 Please follow MinIO [Contributor's Guide](https://github.com/minio/mc/blob/master/CONTRIBUTING.md) 250 251 ## License 252 Use 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.