S3 API - Nscale

nscale s3api is an S3 client built into the CLI. For the operations it supports, it follows aws s3api, plus presign from aws s3: the same flag names and the same PascalCase response bodies. Use it to work with buckets and objects on an Object Storage endpoint without installing or configuring the AWS CLI. Aliases: s3api, s3

To create object storage endpoints, identity policies, and access keys, use nscale object-storage. nscale s3api works with the buckets and objects inside an endpoint.

Quick start

Save a profile

Run configure and follow the prompts. It asks for a profile name (default default), lets you pick an organization and object storage endpoint, and then either creates a new access key or takes the ID and secret of an existing one.

nscale s3api configure

Run commands

Commands use the default profile automatically. Pass --profile to use another one.

nscale s3api create-bucket --bucket my-bucket
nscale s3api put-object --bucket my-bucket --key data.csv --body ./data.csv
nscale s3api list-objects-v2 --bucket my-bucket -q '.Contents[]?.Key'

Endpoint and credentials

Every s3api command accepts these flags to choose the endpoint and credentials:

Flag	Description
`--profile string`	Profile to use. A profile saved with `configure` is checked first, then an AWS shared-config profile of the same name
`--id string`	Object storage endpoint ID. The CLI looks up the endpoint’s public URL through the Nscale API, so you must be logged in
`--endpoint-url string`	Object storage endpoint URL, used as given. Mutually exclusive with `--id`
`--org string`	Organization ID, used to look up the endpoint by `--id` or to pick one interactively

The CLI resolves credentials and the endpoint in this order:

Saved profile. If a profile named by --profile (or default when --profile is not set) exists in object-storage-profiles.yaml, its access key and endpoint URL are used. --endpoint-url or --id override the saved endpoint URL.
AWS credential chain. Otherwise, credentials come from the AWS default chain, the same as the AWS CLI: the AWS profile named by --profile or AWS_PROFILE, the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, and the files in ~/.aws. The endpoint comes from --endpoint-url or --id, then from an endpoint_url in the AWS profile or AWS_ENDPOINT_URL. If none is set, the CLI prompts you to pick an endpoint.

Saved profiles live in object-storage-profiles.yaml in the CLI config directory: ~/.config/nscale/ on macOS and Linux (or $XDG_CONFIG_HOME/nscale/ when set), and %AppData%\nscale\ on Windows. The file stores access key secrets in plain text and is readable only by your user.

default:
  access_key_id: <access-key-id>
  access_key_secret: <access-key-secret>
  endpoint_url: https://<endpoint-dns-name>

Output

s3api commands print the S3 response object as JSON, exactly as the AWS SDK returns it: PascalCase keys and no metadata/spec/status envelope. Use -q with a jq filter to pick out fields:

# Bucket names, one per line
nscale s3api list-buckets -q '.Buckets[]?.Name'

# Keys and sizes under a prefix
nscale s3api list-objects-v2 --bucket my-bucket --prefix logs/ -q '.Contents[]?.Key' -q '.Contents[]?.Size'

S3 leaves empty lists out of the response, so a listing with no matches has no Contents field and .Contents[] fails. Use .Contents[]? in scripts that may list an empty prefix. Commands that change bucket configuration (put-bucket-*, delete-bucket-lifecycle, delete-bucket-tagging) and delete-bucket print a confirmation message instead of a response body. get-object streams the object itself to stdout unless you pass --outfile.

Input values

Flags that take a structured value, such as --delete, --multipart-upload, --lifecycle-configuration, --versioning-configuration, --create-bucket-configuration, and --tagging on the bucket and object tagging commands, accept either inline JSON in the AWS SDK shape or a file:// path to a file that holds it:

nscale s3api put-bucket-versioning --bucket my-bucket --versioning-configuration '{"Status":"Enabled"}'
nscale s3api delete-objects --bucket my-bucket --delete file://delete.json --yes

Date and time flags take RFC3339 timestamps, for example 2026-01-31T12:00:00Z.

Pagination

The list commands follow the AWS CLI pagination model and fetch every page by default:

--max-items caps the total number of items returned across all pages.
--page-size caps the number of items requested in each call to the endpoint.
--starting-token resumes a listing from the continuation token in a previous response, such as NextContinuationToken from list-objects-v2, NextMarker from list-objects, or NextToken from list-object-versions and list-multipart-uploads.

nscale s3api list-objects-v2 --bucket my-bucket --max-items 100

Subcommands

Each command lists its common flags first. The rest, such as server-side encryption, ACLs, Object Lock, and requester-pays settings, are under Advanced flags.

Advanced flags are passed to the S3 API as given. Nscale Object Storage does not implement every S3 feature, for example SSE-C, public ACLs, lifecycle rules, and suspending versioning. See S3 API compatibility.

Setup

configure — Save an s3api profile (endpoint and access key) for reuse

Buckets

list-buckets — List buckets owned by the authenticated account
create-bucket — Create a new bucket
head-bucket — Check whether a bucket exists and is accessible
get-bucket-location — Get the region a bucket resides in
delete-bucket — Delete an empty bucket

Bucket configuration

get-bucket-versioning — Get the versioning state of a bucket
put-bucket-versioning — Set the versioning state of a bucket
get-bucket-lifecycle-configuration — Get the lifecycle configuration of a bucket
put-bucket-lifecycle-configuration — Set the lifecycle configuration of a bucket
delete-bucket-lifecycle — Delete the lifecycle configuration of a bucket
get-bucket-tagging — Get the tag set of a bucket
put-bucket-tagging — Set the tags of a bucket
delete-bucket-tagging — Delete the tags from a bucket

Objects

list-objects-v2 — List objects in a bucket (S3 ListObjectsV2)
list-objects — List objects in a bucket (legacy S3 ListObjects V1)
list-object-versions — List object versions and delete markers in a bucket
put-object — Add an object to a bucket, streaming the body from a file or stdin
get-object — Retrieve an object from a bucket, streaming it to a file or stdout
head-object — Retrieve metadata from an object without returning the object itself
copy-object — Create a copy of an object already stored in the bucket
delete-object — Remove an object from a bucket
delete-objects — Delete multiple objects from a bucket in a single request
presign — Generate a pre-signed URL for an object

Object tagging

get-object-tagging — Get the tag-set of an object
put-object-tagging — Set the tag-set of an object
delete-object-tagging — Remove the entire tag-set from an object

Multipart uploads

create-multipart-upload — Initiate a multipart upload and return its upload ID
upload-part — Upload a part in a multipart upload
upload-part-copy — Upload a part by copying data from an existing object
list-parts — List the parts uploaded for a specific multipart upload
list-multipart-uploads — List in-progress multipart uploads in a bucket
complete-multipart-upload — Complete a multipart upload by assembling its uploaded parts
abort-multipart-upload — Abort a multipart upload and discard its uploaded parts

configure

Save an s3api profile so later commands can run with just --profile. Run it interactively to be prompted for the profile name, the endpoint, and the access key. When the endpoint is picked from your organization or passed with --id, configure can create a new access key for you; the secret is saved to the profile and not printed. To run it without prompts, pass --profile, an endpoint (--endpoint-url or --id), --key-id, and --key-secret. Read the secret from an environment variable rather than typing it inline, so it does not end up in your shell history. An existing profile with the same name is overwritten; interactively, you are asked to confirm first.

nscale s3api configure [flags]

Flags

Flag	Description
Access key ID (skips the access-key prompt)
Access key secret (skips the access-key prompt)

Examples

# Interactive: pick an endpoint and create an access key
nscale s3api configure

# Non-interactive, with an existing access key from the environment
nscale s3api configure --profile prod --id <endpoint-id> \
  --key-id "$ACCESS_KEY_ID" --key-secret "$ACCESS_KEY_SECRET"

list-buckets

List the buckets owned by the access key’s account.

nscale s3api list-buckets [flags]

Flags

Flag	Description
Total number of items to return across all pages
Number of items to request per service call
Limit the response to bucket names with this prefix
Pagination token marking where a previous listing should resume
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Examples

nscale s3api list-buckets
nscale s3api list-buckets --prefix logs- -q '.Buckets[]?.Name'

create-bucket

Create a new bucket.

nscale s3api create-bucket --bucket <bucket> [flags]

Flags

Flag	Description
Required. The name of the bucket to create
The canned ACL to apply to the bucket (`private` \| `public-read` \| `public-read-write` \| `authenticated-read`)
The configuration for the bucket, as JSON
Enable S3 Object Lock for the new bucket
Object ownership for the bucket (`BucketOwnerPreferred` \| `ObjectWriter` \| `BucketOwnerEnforced`)
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Example

nscale s3api create-bucket --bucket my-bucket

head-bucket

Check whether a bucket exists and you have permission to access it. The command fails if the bucket does not exist or is not accessible.

nscale s3api head-bucket --bucket <bucket> [flags]

Flags

Flag	Description
Required. The name of the bucket to check
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Example

nscale s3api head-bucket --bucket my-bucket

get-bucket-location

Get the region a bucket resides in.

nscale s3api get-bucket-location --bucket <bucket> [flags]

Flags

Flag	Description
Required. The name of the bucket
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Example

nscale s3api get-bucket-location --bucket my-bucket -q '.LocationConstraint'

delete-bucket

Delete a bucket. The bucket must be empty: delete its objects first, including every object version when versioning is enabled.

nscale s3api delete-bucket --bucket <bucket> [flags]

Flags

Flag	Description
Required. The name of the bucket to delete
Automatically confirm bucket deletion

Example

nscale s3api delete-bucket --bucket my-bucket --yes

get-bucket-versioning

Get the versioning state of a bucket.

nscale s3api get-bucket-versioning --bucket <bucket> [flags]

Flags

Flag	Description
Required. The name of the bucket
Account ID of the expected bucket owner
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Example

nscale s3api get-bucket-versioning --bucket my-bucket -q '.Status'

put-bucket-versioning

Set the versioning state of a bucket. Nscale Object Storage supports enabling versioning but not suspending it once enabled. --versioning-configuration takes JSON in the SDK VersioningConfiguration shape, or a file:// reference to it.

nscale s3api put-bucket-versioning --bucket <bucket> --versioning-configuration <json> [flags]

Flags

Flag	Description
Required. The name of the bucket
Required. Versioning state, as JSON matching the SDK VersioningConfiguration shape or a `file://` reference

Advanced flags

Flag	Description
Algorithm used to create the request checksum (`CRC32` \| `CRC32C` \| `CRC64NVME` \| `SHA1` \| `SHA256`)
Base64-encoded 128-bit MD5 digest for an integrity check
Account ID of the expected bucket owner
MFA device serial number, a space, and the current MFA code

Example

nscale s3api put-bucket-versioning --bucket my-bucket --versioning-configuration '{"Status":"Enabled"}'

get-bucket-lifecycle-configuration

Nscale Object Storage does not support lifecycle configuration. This command is for other S3-compatible endpoints; see S3 API compatibility.

Get the lifecycle configuration of a bucket.

nscale s3api get-bucket-lifecycle-configuration --bucket <bucket> [flags]

Flags

Flag	Description
Required. The name of the bucket
Account ID of the expected bucket owner
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Example

nscale s3api get-bucket-lifecycle-configuration --bucket my-bucket -q '.Rules[].ID'

put-bucket-lifecycle-configuration

Nscale Object Storage does not support lifecycle configuration. This command is for other S3-compatible endpoints; see S3 API compatibility.

Set the lifecycle configuration of a bucket, replacing any existing rules. --lifecycle-configuration takes JSON in the SDK BucketLifecycleConfiguration shape, or a file:// reference to it.

nscale s3api put-bucket-lifecycle-configuration --bucket <bucket> --lifecycle-configuration <json> [flags]

Flags

Flag	Description
Required. The name of the bucket
Algorithm used to create the request checksum (`CRC32` \| `CRC32C` \| `CRC64NVME` \| `SHA1` \| `SHA256`)
Account ID of the expected bucket owner
Lifecycle rules, as JSON matching the SDK BucketLifecycleConfiguration shape or a `file://` reference
Default minimum object size behaviour (`varies_by_storage_class` \| `all_storage_classes_128K`)

Examples

# Expire objects under logs/ after 30 days
nscale s3api put-bucket-lifecycle-configuration --bucket my-bucket \
  --lifecycle-configuration '{"Rules":[{"ID":"expire-logs","Status":"Enabled","Filter":{"Prefix":"logs/"},"Expiration":{"Days":30}}]}'

nscale s3api put-bucket-lifecycle-configuration --bucket my-bucket --lifecycle-configuration file://lifecycle.json

delete-bucket-lifecycle

Nscale Object Storage does not support lifecycle configuration. This command is for other S3-compatible endpoints; see S3 API compatibility.

Delete the lifecycle configuration of a bucket.

nscale s3api delete-bucket-lifecycle --bucket <bucket> [flags]

Flags

Flag	Description
Required. The name of the bucket
Account ID of the expected bucket owner

Example

nscale s3api delete-bucket-lifecycle --bucket my-bucket

get-bucket-tagging

Get the tag set of a bucket.

nscale s3api get-bucket-tagging --bucket <bucket> [flags]

Flags

Flag	Description
Required. The name of the bucket
Account ID of the expected bucket owner
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Example

nscale s3api get-bucket-tagging --bucket my-bucket -q '.TagSet[] | "\(.Key)=\(.Value)"'

put-bucket-tagging

Set the tags of a bucket, replacing any existing tags. Pass the tags as key=value pairs with --tags, or as JSON in the SDK Tagging shape with --tagging. Use --tagging when a value contains a comma.

nscale s3api put-bucket-tagging --bucket <bucket> (--tags <pairs> | --tagging <json>) [flags]

Flags

Flag	Description
Required. The name of the bucket
Algorithm used to create the request checksum (`CRC32` \| `CRC32C` \| `CRC64NVME` \| `SHA1` \| `SHA256`)
Base64-encoded 128-bit MD5 digest of the data
Account ID of the expected bucket owner
Tag-set, as JSON matching the SDK Tagging shape or a `file://` reference; required unless is given
Tag-set shorthand as `key=value` pairs, or a `file://` reference to them; an alternative to . Use for values that contain a comma

Examples

nscale s3api put-bucket-tagging --bucket my-bucket --tags 'env=prod,team=data'
nscale s3api put-bucket-tagging --bucket my-bucket --tagging '{"TagSet":[{"Key":"env","Value":"prod"}]}'

delete-bucket-tagging

Delete the tags from a bucket.

nscale s3api delete-bucket-tagging --bucket <bucket> [flags]

Flags

Flag	Description
Required. The name of the bucket
Account ID of the expected bucket owner

Example

nscale s3api delete-bucket-tagging --bucket my-bucket

list-objects-v2

List the objects in a bucket with the S3 ListObjectsV2 operation. Use --prefix to list a “directory” and --delimiter / to group deeper keys into CommonPrefixes.

nscale s3api list-objects-v2 --bucket <bucket> [flags]

Flags

Flag	Description
Required. The bucket to list objects from
Character used to group keys into common prefixes
Encoding used for object keys in the response (`url`)
Account ID of the expected bucket owner
Return the owner field for each key
Total number of items to return across all pages
Number of items to request per service call
Limit the response to keys that begin with this prefix
Confirms the requester will be charged for the request (`requester`)
Start listing after this key
Pagination token marking where a previous listing should resume
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Examples

nscale s3api list-objects-v2 --bucket my-bucket
nscale s3api list-objects-v2 --bucket my-bucket --prefix logs/ --delimiter / -q '.CommonPrefixes[]?.Prefix'
nscale s3api list-objects-v2 --bucket my-bucket --max-items 100 -q '.Contents[]?.Key'

list-objects

List the objects in a bucket with the legacy S3 ListObjects (V1) operation. Prefer list-objects-v2 unless a tool depends on the V1 response shape.

nscale s3api list-objects --bucket <bucket> [flags]

Flags

Flag	Description
Required. The bucket to list objects from
Character used to group keys into common prefixes
Encoding used for object keys in the response (`url`)
Account ID of the expected bucket owner
Key to start listing from
Total number of items to return across all pages
Number of items to request per service call
Limit the response to keys that begin with this prefix
Confirms the requester will be charged for the request (`requester`)
Pagination token marking where a previous listing should resume
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Example

nscale s3api list-objects --bucket my-bucket --prefix logs/

list-object-versions

List every version of the objects in a bucket, and any delete markers.

nscale s3api list-object-versions --bucket <bucket> [flags]

Flags

Flag	Description
Required. The bucket to list object versions from
Character used to group keys into common prefixes
Encoding used for object keys in the response (`url`)
Account ID of the expected bucket owner
Key to start listing from
Total number of items to return across all pages
Number of items to request per service call
Limit the response to keys that begin with this prefix
Confirms the requester will be charged for the request (`requester`)
Pagination token marking where a previous listing should resume
Version ID to start listing from
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Examples

nscale s3api list-object-versions --bucket my-bucket --prefix data.csv
nscale s3api list-object-versions --bucket my-bucket -q '.Versions[]?.VersionId'

put-object

Upload an object to a bucket. The body streams from the file named by --body, or from stdin when --body - is passed, so large files are not read into memory. Omitting --body creates an empty object.

nscale s3api put-object --bucket <bucket> --key <key> [--body <path>] [flags]

Flags

Flag	Description
Required. The target bucket
Required. The object key
Path to the object data; `-` reads from stdin (streamed, not buffered); omitted uploads an empty object
Standard MIME type describing the content format
Metadata to store with the object, as JSON or `key=value` pairs (or a `file://` reference)
Tag-set for the object, URL query encoded
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Advanced flags

Flag	Description
Canned ACL to apply to the object
Toggle an S3 Bucket Key for SSE-KMS encryption
Caching behaviour along the request/reply chain
Algorithm used to create the object checksum
Base64 CRC32 checksum for data integrity
Base64 CRC32C checksum for data integrity
Base64 CRC64NVME checksum for data integrity
Base64 MD5 checksum for data integrity
Base64 SHA1 checksum for data integrity
Base64 SHA256 checksum for data integrity
Presentational information for the object
Content encodings applied to the object
The language the content is in
Size of the body in bytes
Base64-encoded 128-bit MD5 digest for an integrity check
Account ID of the expected bucket owner
Date/time the object is no longer cacheable (RFC3339)
Grants READ, READ_ACP, and WRITE_ACP permissions on the object
Allows grantee to read the object and its metadata
Allows grantee to read the object ACL
Allows grantee to write the object ACL
Upload only if the provided ETag matches the existing object
Upload only if the object key does not already exist
Whether a legal hold applies to the object (`ON` \| `OFF`)
Object Lock mode to apply to the object (`GOVERNANCE` \| `COMPLIANCE`)
When the object’s Object Lock expires (RFC3339)
Confirms the requester will be charged (`requester`)
Server-side encryption algorithm to use (`AES256` \| `aws:kms` \| `aws:kms:dsse`)
Algorithm to use when encrypting the object (SSE-C)
Customer-provided encryption key (SSE-C)
128-bit MD5 digest of the SSE-C encryption key
Base64-encoded KMS encryption context for the object
KMS key ID to use for object encryption
Storage class for the object. Default: `STANDARD`
Redirect requests for this object to another object or URL
Offset for appending data to an existing object

Examples

nscale s3api put-object --bucket my-bucket --key data.csv --body ./data.csv --content-type text/csv

# Stream from another command
tar -cz ./results | nscale s3api put-object --bucket my-bucket --key results.tar.gz --body -

# Store metadata and tags with the object
nscale s3api put-object --bucket my-bucket --key report.pdf --body ./report.pdf \
  --metadata 'owner=data-team' --tagging 'env=prod&team=data'

get-object

Download an object. Without --outfile, or with --outfile -, the object streams to stdout and nothing else is printed. With --outfile, the object is written to that file and the response metadata is printed as JSON. --json and -q require --outfile.

nscale s3api get-object --bucket <bucket> --key <key> [--outfile <path>] [flags]

Flags

Flag	Description
Required. The bucket containing the object
Required. The key of the object to get
Path to write the object to; `-` or omitted streams to stdout
Part number of the object being read
Download only the specified byte range of the object
Reference a specific version of the object
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Advanced flags

Flag	Description
Enable checksum retrieval (`ENABLED`)
Account ID of the expected bucket owner
Return the object only if its ETag matches this value
Return the object only if modified since this time (RFC3339)
Return the object only if its ETag differs from this value
Return the object only if not modified since this time (RFC3339)
Confirms the requester will be charged (`requester`)
Sets the Cache-Control header of the response
Sets the Content-Disposition header of the response
Sets the Content-Encoding header of the response
Sets the Content-Language header of the response
Sets the Content-Type header of the response
Sets the Expires header of the response (RFC3339)
Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C)
Customer-provided encryption key (SSE-C)
128-bit MD5 digest of the SSE-C encryption key

Examples

nscale s3api get-object --bucket my-bucket --key data.csv --outfile ./data.csv

# Stream to another command
nscale s3api get-object --bucket my-bucket --key data.csv | head

# Download the first kilobyte of a specific version
nscale s3api get-object --bucket my-bucket --key data.csv --version-id <version-id> --range bytes=0-1023 --outfile ./head.csv

head-object

Get an object’s metadata, such as its size, ETag, content type, and user metadata, without downloading it.

nscale s3api head-object --bucket <bucket> --key <key> [flags]

Flags

Flag	Description
Required. The bucket containing the object
Required. The object key
Part number of the object being read
HTTP Range header for the requested byte range
Reference a specific version of the object
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Advanced flags

Flag	Description
Enable checksum retrieval (`ENABLED`)
Account ID of the expected bucket owner
Return the object only if its ETag matches this value
Return the object only if modified since this time (RFC3339)
Return the object only if its ETag differs from this value
Return the object only if not modified since this time (RFC3339)
Confirms the requester will be charged (`requester`)
Sets the Cache-Control header of the response
Sets the Content-Disposition header of the response
Sets the Content-Encoding header of the response
Sets the Content-Language header of the response
Sets the Content-Type header of the response
Sets the Expires header of the response (RFC3339)
Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C)
Customer-provided encryption key (SSE-C)
128-bit MD5 digest of the SSE-C encryption key

Example

nscale s3api head-object --bucket my-bucket --key data.csv -q '.ContentLength'

copy-object

Copy an object that is already stored in object storage. --copy-source names the source as bucket/key, optionally with ?versionId=<version-id>; pass the key unencoded, since the CLI URL-encodes it for you.

nscale s3api copy-object --bucket <bucket> --key <key> --copy-source <bucket/key> [flags]

Flags

Flag	Description
Required. The destination bucket
Required. The source object as `bucket/key[?versionId=…]`, given raw/unencoded — the key is URL-encoded for you
Required. The key of the destination object
Standard MIME type describing the object data
Metadata to store with the object, as JSON or `key=value` pairs (with )
Tag-set for the destination object, URL query encoded
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Advanced flags

Flag	Description
Canned ACL to apply to the object
Toggle an S3 Bucket Key for SSE-KMS encryption
Caching behaviour along the request/reply chain
Algorithm S3 uses to create the object checksum
Presentational information for the object
Content encodings applied to the object
The language the content is in
Copy only if the source ETag matches this value
Copy only if the source was modified since this time (RFC3339)
Copy only if the source ETag differs from this value
Copy only if the source was not modified since this time (RFC3339)
Algorithm to use when decrypting the source object (SSE-C)
Customer-provided key to decrypt the source object (SSE-C)
128-bit MD5 digest of the source SSE-C key
Account ID of the expected destination bucket owner
Account ID of the expected source bucket owner
Date/time the object is no longer cacheable (RFC3339)
Grants READ, READ_ACP, and WRITE_ACP permissions on the object
Allows grantee to read the object and its metadata
Allows grantee to read the object ACL
Allows grantee to write the object ACL
Copy only if the destination object ETag matches this value
Copy only if the destination key does not already exist
Whether metadata is copied from the source or replaced (`COPY` \| `REPLACE`)
Whether a legal hold applies to the copy (`ON` \| `OFF`)
Object Lock mode to apply to the copy (`GOVERNANCE` \| `COMPLIANCE`)
When the copy’s Object Lock expires (RFC3339)
Confirms the requester will be charged (`requester`)
Server-side encryption algorithm to use (`AES256` \| `aws:kms` \| `aws:kms:dsse`)
Algorithm to use when encrypting the destination object (SSE-C)
Customer-provided encryption key (SSE-C)
128-bit MD5 digest of the SSE-C encryption key
Base64-encoded KMS encryption context for the destination object
KMS key ID to use for object encryption
Storage class for the copied object
Whether the tag-set is copied from the source or replaced (`COPY` \| `REPLACE`)
Redirect requests for this copy to another object or URL

Examples

nscale s3api copy-object --bucket backup-bucket --key data.csv --copy-source my-bucket/data.csv

# Replace the metadata on the copy
nscale s3api copy-object --bucket my-bucket --key data.csv --copy-source my-bucket/data.csv \
  --metadata-directive REPLACE --content-type text/csv --metadata 'owner=data-team'

delete-object

Delete an object. In a versioned bucket, this adds a delete marker unless you pass --version-id to delete a specific version.

nscale s3api delete-object --bucket <bucket> --key <key> [flags]

Flags

Flag	Description
Required. The bucket containing the object
Required. The key of the object to delete
Reference a specific version of the object
Automatically confirm object deletion
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Advanced flags

Flag	Description
Bypass Governance-mode Object Lock restrictions
Account ID of the expected bucket owner
Delete only if the object’s ETag matches this value
Delete only if the object’s last-modified time matches this value (RFC3339)
Delete only if the object size matches this many bytes
MFA device serial number and code for versioned deletes
Confirms the requester will be charged (`requester`)

Examples

nscale s3api delete-object --bucket my-bucket --key data.csv --yes
nscale s3api delete-object --bucket my-bucket --key data.csv --version-id <version-id> --yes

delete-objects

Delete multiple objects from a bucket in a single request. --delete takes JSON in the SDK Delete shape, or a file:// reference to it.

nscale s3api delete-objects --bucket <bucket> --delete <json> [flags]

Flags

Flag	Description
Required. The bucket containing the objects
Required. Objects to delete, as JSON matching the SDK Delete shape or a `file://` reference
Automatically confirm object deletion
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Advanced flags

Flag	Description
Bypass Governance-mode Object Lock restrictions
Algorithm used to create the object checksum (`CRC32` \| `CRC32C` \| `CRC64NVME` \| `SHA1` \| `SHA256`)
Account ID of the expected bucket owner
MFA device serial number and code for versioned deletes
Confirms the requester will be charged (`requester`)

Examples

nscale s3api delete-objects --bucket my-bucket --delete '{"Objects":[{"Key":"a.csv"},{"Key":"b.csv"}]}' --yes
nscale s3api delete-objects --bucket my-bucket --delete file://delete.json --yes

presign

Generate a pre-signed URL that lets anyone who holds it download the object with a plain HTTP GET until it expires. This is the equivalent of aws s3 presign. See Share objects with pre-signed URLs for guidance on using them safely. The URL is signed locally with the resolved credentials, so it stops working early if the access key is deleted or temporary credentials expire. The command prints the bare URL; --json and -q return it together with its expiry time as URL and ExpiresAt.

nscale s3api presign s3://<bucket>/<key> [flags]

Flags

Flag	Description
Number of seconds until the pre-signed URL expires (max 604800). Default: `3600`
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Examples

# Valid for 1 hour (the default)
nscale s3api presign s3://my-bucket/report.pdf

# Valid for 7 days, the maximum
nscale s3api presign s3://my-bucket/report.pdf --expires-in 604800

# Download with the URL, no credentials required
curl -fSL -o report.pdf "$(nscale s3api presign s3://my-bucket/report.pdf)"

get-object-tagging

Get the tag-set of an object.

nscale s3api get-object-tagging --bucket <bucket> --key <key> [flags]

Flags

Flag	Description
Required. The name of the bucket
Required. Object key to get the tagging for
Account ID of the expected bucket owner
Confirms the requester will be charged (`requester`)
Version ID of the object
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Example

nscale s3api get-object-tagging --bucket my-bucket --key data.csv -q '.TagSet'

put-object-tagging

Set the tag-set of an object, replacing any existing tags. Pass the tags as key=value pairs with --tags, or as JSON in the SDK Tagging shape with --tagging. Use --tagging when a value contains a comma.

nscale s3api put-object-tagging --bucket <bucket> --key <key> (--tags <pairs> | --tagging <json>) [flags]

Flags

Flag	Description
Required. The name of the bucket
Required. Name of the object key
Tag-set, as JSON matching the SDK Tagging shape or a `file://` reference; required unless is given
Tag-set shorthand as `key=value` pairs, or a `file://` reference to them; an alternative to . Use for values that contain a comma
Version ID the tag-set is added to
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Advanced flags

Flag	Description
Algorithm used to create the request checksum (`CRC32` \| `CRC32C` \| `CRC64NVME` \| `SHA1` \| `SHA256`)
MD5 hash for the request body
Account ID of the expected bucket owner
Confirms the requester will be charged (`requester`)

Examples

nscale s3api put-object-tagging --bucket my-bucket --key data.csv --tags 'env=prod,team=data'
nscale s3api put-object-tagging --bucket my-bucket --key data.csv --tagging '{"TagSet":[{"Key":"env","Value":"prod"}]}'

delete-object-tagging

Remove the entire tag-set from an object.

nscale s3api delete-object-tagging --bucket <bucket> --key <key> [flags]

Flags

Flag	Description
Required. The name of the bucket
Required. Key identifying the object to remove tags from
Account ID of the expected bucket owner
Version ID the tag-set is removed from
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Example

nscale s3api delete-object-tagging --bucket my-bucket --key data.csv

create-multipart-upload

Start a multipart upload and return its UploadId. Upload the parts with upload-part or upload-part-copy, then assemble them with complete-multipart-upload. The object’s metadata, tags, and storage class are set here, not when the upload completes.

nscale s3api create-multipart-upload --bucket <bucket> --key <key> [flags]

Flags

Flag	Description
Required. The bucket to create the object in
Required. The object key
Standard MIME type describing the content format
Metadata to store with the object, as JSON or `key=value` pairs (or a `file://` reference)
Tag-set for the object, URL query encoded
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Advanced flags

Flag	Description
Canned ACL to apply to the object
Toggle an S3 Bucket Key for SSE-KMS encryption
Caching behaviour along the request/reply chain
Algorithm used to create the object checksum
How the object checksum is calculated across parts (`COMPOSITE` \| `FULL_OBJECT`)
Presentational information for the object
Content encodings applied to the object
The language the content is in
Account ID of the expected bucket owner
Date/time the object is no longer cacheable (RFC3339)
Grants READ, READ_ACP, and WRITE_ACP permissions on the object
Allows grantee to read the object and its metadata
Allows grantee to read the object ACL
Allows grantee to write the object ACL
Whether a legal hold applies to the object (`ON` \| `OFF`)
Object Lock mode to apply to the object (`GOVERNANCE` \| `COMPLIANCE`)
When the object’s Object Lock expires (RFC3339)
Confirms the requester will be charged (`requester`)
Server-side encryption algorithm to use (`AES256` \| `aws:kms` \| `aws:kms:dsse`)
Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C)
Customer-provided encryption key (SSE-C)
128-bit MD5 digest of the SSE-C encryption key
Base64-encoded KMS encryption context for the object
KMS key ID to use for object encryption
Storage class for the object. Default: `STANDARD`
Redirect requests for this object to another object or URL

Example

UPLOAD_ID=$(nscale s3api create-multipart-upload --bucket my-bucket --key large.bin -q '.UploadId')

upload-part

Upload one part of a multipart upload. Part numbers run from 1 to 10000. The body streams from the file named by --body, or from stdin with --body -. Keep the ETag from each response: complete-multipart-upload needs it.

nscale s3api upload-part --bucket <bucket> --key <key> --upload-id <upload-id> --part-number <n> --body <path> [flags]

Flags

Flag	Description
Required. The target bucket
Required. The object key
Required. The part number, between 1 and 10000
Required. The ID identifying the multipart upload
Path to the part data; `-` reads from stdin (streamed, not buffered); omitted uploads an empty part
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Advanced flags

Flag	Description
Algorithm used to create the part checksum
Base64 CRC32 checksum for data integrity
Base64 CRC32C checksum for data integrity
Base64 CRC64NVME checksum for data integrity
Base64 SHA1 checksum for data integrity
Base64 SHA256 checksum for data integrity
Size of the body in bytes
Base64-encoded 128-bit MD5 digest for an integrity check
Account ID of the expected bucket owner
Confirms the requester will be charged (`requester`)
Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C); must match the create-multipart-upload request
Customer-provided encryption key (SSE-C)
128-bit MD5 digest of the SSE-C encryption key

Example

nscale s3api upload-part --bucket my-bucket --key large.bin --upload-id "$UPLOAD_ID" \
  --part-number 1 --body ./large.bin.part1 -q '.ETag'

upload-part-copy

Upload one part of a multipart upload by copying data from an existing object. Use --copy-source-range to copy only part of the source object.

nscale s3api upload-part-copy --bucket <bucket> --key <key> --upload-id <upload-id> --part-number <n> --copy-source <bucket/key> [flags]

Flags

Flag	Description
Required. The destination bucket
Required. The source object as `bucket/key[?versionId=…]`, given raw/unencoded — the key is URL-encoded for you
Required. The key of the destination object
Required. The part number, between 1 and 10000
Required. The ID identifying the multipart upload
The byte range of the source object to copy
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Advanced flags

Flag	Description
Copy only if the source ETag matches this value
Copy only if the source was modified since this time (RFC3339)
Copy only if the source ETag differs from this value
Copy only if the source was not modified since this time (RFC3339)
Algorithm to use when decrypting the source object (SSE-C)
Customer-provided key to decrypt the source object (SSE-C)
128-bit MD5 digest of the source SSE-C key
Account ID of the expected destination bucket owner
Account ID of the expected source bucket owner
Confirms the requester will be charged (`requester`)
Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C)
Customer-provided encryption key (SSE-C)
128-bit MD5 digest of the SSE-C encryption key

Example

nscale s3api upload-part-copy --bucket my-bucket --key large.bin --upload-id "$UPLOAD_ID" \
  --part-number 2 --copy-source my-bucket/source.bin --copy-source-range bytes=0-104857599

list-parts

List the parts uploaded so far for a multipart upload.

nscale s3api list-parts --bucket <bucket> --key <key> --upload-id <upload-id> [flags]

Flags

Flag	Description
Required. The bucket the multipart upload targets
Required. The object key of the multipart upload
Required. The ID identifying the multipart upload
Total number of items to return across all pages
Number of items to request per service call
Part number after which listing begins
Pagination token marking where a previous listing should resume
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Advanced flags

Flag	Description
Account ID of the expected bucket owner
Confirms the requester will be charged for the request (`requester`)
Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C); must match the create-multipart-upload request
Customer-provided encryption key (SSE-C)
128-bit MD5 digest of the SSE-C encryption key

Example

nscale s3api list-parts --bucket my-bucket --key large.bin --upload-id "$UPLOAD_ID" \
  -q '.Parts[]?.PartNumber' -q '.Parts[]?.ETag'

list-multipart-uploads

List the multipart uploads in a bucket that have started but not yet been completed or aborted. Incomplete uploads keep their parts stored until you abort them.

nscale s3api list-multipart-uploads --bucket <bucket> [flags]

Flags

Flag	Description
Required. The bucket to list multipart uploads from
Character used to group keys into common prefixes
Encoding used for object keys in the response (`url`)
Account ID of the expected bucket owner
Key to start listing from
Total number of items to return across all pages
Number of items to request per service call
Limit the response to keys that begin with this prefix
Confirms the requester will be charged for the request (`requester`)
Pagination token marking where a previous listing should resume
Upload ID to start listing from (used with )
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Example

nscale s3api list-multipart-uploads --bucket my-bucket -q '.Uploads[]?.Key' -q '.Uploads[]?.UploadId'

complete-multipart-upload

Complete a multipart upload by assembling its parts into one object. --multipart-upload lists every part by PartNumber and ETag, as JSON in the SDK CompletedMultipartUpload shape or a file:// reference to it. The quickest way to build it is from list-parts.

nscale s3api complete-multipart-upload --bucket <bucket> --key <key> --upload-id <upload-id> --multipart-upload <json> [flags]

Flags

Flag	Description
Required. The target bucket
Required. The object key
Required. The parts to assemble, as JSON or a `file://` reference
Required. The ID identifying the multipart upload
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Advanced flags

Flag	Description
Base64 CRC32 checksum of the full object
Base64 CRC32C checksum of the full object
Base64 CRC64NVME checksum of the full object
Base64 SHA1 checksum of the full object
Base64 SHA256 checksum of the full object
How the object checksum is calculated across parts (`COMPOSITE` \| `FULL_OBJECT`)
Account ID of the expected bucket owner
Complete only if the existing object’s ETag matches this value
Complete only if the object key does not already exist
Expected total size of the assembled object in bytes
Confirms the requester will be charged (`requester`)
Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C); must match the upload-part requests
Customer-provided encryption key (SSE-C)
128-bit MD5 digest of the SSE-C encryption key

Examples

# Build the parts list from the uploaded parts
nscale s3api list-parts --bucket my-bucket --key large.bin --upload-id "$UPLOAD_ID" \
  -q '{Parts: [.Parts[]? | {ETag, PartNumber}]}' > parts.json

nscale s3api complete-multipart-upload --bucket my-bucket --key large.bin --upload-id "$UPLOAD_ID" \
  --multipart-upload file://parts.json

abort-multipart-upload

Abort a multipart upload and discard the parts uploaded so far.

nscale s3api abort-multipart-upload --bucket <bucket> --key <key> --upload-id <upload-id> [flags]

Flags

Flag	Description
Required. The bucket the multipart upload targets
Required. The object key of the multipart upload
Required. The ID identifying the multipart upload to abort
Account ID of the expected bucket owner
Abort only if the upload was initiated at this time (RFC3339)
Confirms the requester will be charged (`requester`)
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

Example

nscale s3api abort-multipart-upload --bucket my-bucket --key large.bin --upload-id "$UPLOAD_ID"

Object Storage (CLI)

Manage object storage endpoints, identity policies, and access keys.

Object Storage (Console)

Create and manage object storage via the Console UI.

​Quick start

​Endpoint and credentials

​Output

​Input values

​Pagination

​Subcommands

​configure

​Flags

​Examples

​list-buckets

​Flags

​Examples

​create-bucket

​Flags

​Example

​head-bucket

​Flags

​Example

​get-bucket-location

​Flags

​Example

​delete-bucket

​Flags

​Example

​get-bucket-versioning

​Flags

​Example

​put-bucket-versioning

​Flags

​Example

​get-bucket-lifecycle-configuration

​Flags

​Example

​put-bucket-lifecycle-configuration

​Flags

​Examples

​delete-bucket-lifecycle

​Flags

​Example

​get-bucket-tagging

​Flags

​Example

​put-bucket-tagging

​Flags

​Examples

​delete-bucket-tagging

​Flags

​Example

​list-objects-v2

​Flags

​Examples

​list-objects

​Flags

​Example

​list-object-versions

​Flags

​Examples

​put-object

​Flags

​Examples

​get-object

​Flags

​Examples

​head-object

​Flags

​Example

​copy-object

​Flags

​Examples

​delete-object

​Flags

​Examples

​delete-objects

​Flags

​Examples

​presign

​Flags

​Examples

​get-object-tagging

​Flags

Quick start

Endpoint and credentials

Output

Input values

Pagination

Subcommands

configure

Flags

Examples

list-buckets

Flags

Examples

create-bucket

Flags

Example

head-bucket

Flags

Example

get-bucket-location

Flags

Example

delete-bucket

Flags

Example

get-bucket-versioning

Flags

Example

put-bucket-versioning

Flags

Example

get-bucket-lifecycle-configuration

Flags

Example

put-bucket-lifecycle-configuration

Flags

Examples

delete-bucket-lifecycle

Flags

Example

get-bucket-tagging

Flags

Example

put-bucket-tagging

Flags

Examples

delete-bucket-tagging

Flags

Example

list-objects-v2

Flags

Examples

list-objects

Flags

Example

list-object-versions

Flags

Examples

put-object

Flags

Examples

get-object

Flags

Examples

head-object

Flags

Example

copy-object

Flags

Examples

delete-object

Flags

Examples

delete-objects

Flags

Examples

presign

Flags

Examples

get-object-tagging

Flags