> For the complete documentation index, see [llms.txt](https://docs.nebulablock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nebulablock.com/products/object-storage/s3cmd-linux-macos.md).

# s3cmd on Linux and macOS

Configure s3cmd on Linux or macOS to manage Nebula Block object storage from the command line.

`s3cmd` is the quickest way to work with your buckets from a terminal. Nebula Block object storage speaks the S3 API, so `s3cmd` works against it unchanged once it is pointed at your workspace's endpoint.

> **Tip:** The console generates this configuration for you, already filled in with your endpoint and access keys. Open your workspace under [Object Storage](https://console.nebulablock.com/object-storage), click **View**, and go to the **s3cmd** tab. Copying from there avoids transcription mistakes — the steps below are the same thing, explained.

## 1. Install s3cmd

```bash
# macOS
brew install s3cmd

# Debian / Ubuntu
sudo apt-get install -y s3cmd

# RHEL / CentOS / Fedora
sudo yum install -y s3cmd

# Cross-platform (Python)
pip install s3cmd
```

## 2. Create `~/.s3cfg`

Rather than working through `s3cmd --configure` interactively, write the config file directly. Save this as `~/.s3cfg`, substituting your own keys and hostname:

```ini
[default]
access_key = YOUR_ACCESS_KEY
secret_key = YOUR_SECRET_KEY
host_base = s3-ca-east.nebulablock.com:443
host_bucket = s3-ca-east.nebulablock.com:443
use_https = True
signature_v2 = False
check_ssl_certificate = True
check_ssl_hostname = True
```

Where these values come from:

| Setting                    | Where to find it                                                                                           |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `access_key`, `secret_key` | The **S3 Credentials** panel on your workspace's **Overview** tab. Click the eye icon to reveal the secret |
| `host_base`, `host_bucket` | The **Hostname** shown in that same panel, with `:443` appended                                            |

Two details worth understanding rather than copying blindly:

* **`host_bucket` matches `host_base` and has no `%(bucket)s` placeholder.** That selects path-style addressing (`https://host/bucket/key`). Virtual-hosted style works too, but path-style is what the console's snippet uses and it avoids per-bucket DNS concerns.
* **`signature_v2 = False`** keeps `s3cmd` on AWS Signature Version 4. Do not switch this to `True`.

> **Important:** Your secret key is a credential. Keep `~/.s3cfg` readable only by you (`chmod 600 ~/.s3cfg`), and do not commit it.

## 3. Verify the connection

Listing your buckets confirms both the credentials and the endpoint:

```bash
s3cmd ls
```

If this returns your buckets — or nothing at all, when you have not created any yet — you are configured correctly. An error here almost always means a wrong hostname or a mistyped key.

## Working with buckets

```bash
s3cmd mb s3://YOUR-BUCKET       # create a bucket
s3cmd ls                        # list buckets
s3cmd du s3://YOUR-BUCKET       # show bucket size
s3cmd rb s3://YOUR-BUCKET       # delete a bucket (must be empty)
```

## Working with objects

```bash
s3cmd put local-file.txt s3://YOUR-BUCKET/          # upload one file
s3cmd get s3://YOUR-BUCKET/local-file.txt .         # download one file
s3cmd ls s3://YOUR-BUCKET/                          # list objects
s3cmd sync ./local-folder s3://YOUR-BUCKET/         # sync a folder up
s3cmd sync s3://YOUR-BUCKET/ ./local-folder         # sync a folder down
s3cmd del s3://YOUR-BUCKET/local-file.txt           # delete an object
```

`s3cmd sync` is the right tool for datasets and checkpoints — it transfers only what changed, and it handles large files far better than uploading through the console or the Platform API.

## Generate a presigned URL

Hand out a short-lived URL that anyone can use to download a private object, with no credentials:

```bash
s3cmd signurl s3://YOUR-BUCKET/local-file.txt $(($(date +%s) + 3600))
```

The trailing number is an absolute expiry timestamp — the example above is one hour from now.

## See also

* [s3cmd on Windows](/products/object-storage/s3cmd-windows.md)
* [Python SDK](/products/object-storage/sdk-python.md)
* [Object Storage](/products/object-storage.md)