CLI & Advanced Features

The zcp CLI manages object storage end to end. Instance lifecycle (create, resize, delete, credentials) and bucket creation/listing go through the ZSoftly control plane; everything at the bucket and object level is performed directly against the S3 endpoint (https://objects.<region>.zcp.zsoftly.ca) using access keys that you save when creating them.

The result: the CLI exposes the full S3 feature set of the platform: including many capabilities not available in the portal UI (lifecycle rules, CORS, bucket policies, tagging, presigned URLs, server-side copy/move, object versioning workflows, and multipart cleanup).

Install and configure the CLI first; see Installation and Configuration. The cloud provider for object storage is selected automatically; you only choose a region and project.

Where each feature is available

Capability	Portal UI	zcp CLI	S3 API / SDK
Create / list / resize / delete instance	✅	✅	—
Manage S3 access keys	✅	✅	—
Auto-scaling toggle	✅	—	—
Create / list / delete bucket	✅	✅	✅
Upload / download / delete objects	✅	✅	✅
Folders (key prefixes)	✅	✅	✅
Make a bucket public	✅	✅	✅
Versioning enable / suspend / status	✅	✅	✅
Object Lock (WORM) at bucket creation	✅	planned¹	✅
List / download / delete / restore object versions	—	✅	✅
Presigned download URL (object url)	—	✅	✅
Presigned upload URL (object put-url)	—	✅	✅
Server-side copy / move	—	✅	✅
Object stat (HEAD: size, type, ETag, user metadata)	—	✅	✅
Content-type & user metadata on upload	—	✅	✅
Bucket & object tagging	—	✅	✅
Default encryption (SSE-S3)	—	—²	—²
Raw bucket policy (get/set/delete)	—	✅	✅
Lifecycle / expiration rules	—	✅	✅
CORS rules	—	✅	✅
Incomplete multipart upload cleanup	—	✅	✅
Empty bucket / purge all versions	—	✅	✅

¹ Object Lock can only be enabled when a bucket is created. The portal supports this today; CLI support is planned (see the note at the end of this page). You can also enable it directly against the S3 endpoint with an SDK at bucket creation.

² Default encryption is not supported on this platform yet, in any interface. See Default encryption is not available below.

Anything marked CLI / S3 API only is also available through any S3-compatible SDK. See S3 API Usage for language examples.

Command reference

<storage> is the object-storage instance slug, <key> an object key. <bucket> is the bucket name for every command that reaches the S3 gateway, and the bucket slug only for bucket delete. Print both with zcp object-storage bucket list <storage>. The platform appends a numeric suffix at creation, so neither is the name you originally typed. See S3 API Usage. Add -o json (or -o yaml) to any command for machine-readable output, and -y to skip confirmation prompts.

Note

Object-storage commands require a region and a project. Object storage uses its own regions: os-yul / os-yow (not the compute yul-1/yow-1). Set them with --region/--project, ZCP_REGION/ZCP_PROJECT, or a profile default (zcp profile add). For example: export ZCP_REGION=os-yow ZCP_PROJECT=default-9 before the commands below.

Instance

zcp object-storage list                       # list instances
zcp object-storage get <storage>              # details + S3 endpoint
zcp object-storage keys list <storage>        # access-key metadata
zcp object-storage keys create <storage>      # copy the secret within five minutes
zcp object-storage keys delete <storage> <key-id> -y  # revoke a non-final active key
zcp object-storage resize <storage> --size 200
zcp object-storage delete <storage> -y

# Create — pick an object-storage region (os-yul / os-yow) and a plan slug
zcp plan object-storage                        # list plan slugs + sizes + prices
zcp object-storage create \
  --name my-store --project default \
  --region os-yow --billing-cycle hourly --plan o2100g

Flag (create)	Description
--name	Instance name (required)
--region	Object-storage region: os-yul or os-yow (required)
--billing-cycle	e.g. hourly, monthly (required)
--project	Project slug (or ZCP_PROJECT)
--plan	Plan slug from zcp plan object-storage (storage category is derived from it)
--storage-gb	Custom size in GB (alternative to --plan; min 60)
--storage-category	Override the storage category (rarely needed)

Bucket

zcp object-storage bucket list <storage>
zcp object-storage bucket get <storage> <bucket>
zcp object-storage bucket create <storage> --name my-bucket
zcp object-storage bucket empty <storage> <bucket> -y           # delete all objects + versions
zcp object-storage bucket delete <storage> <bucket> --purge -y  # --purge empties versions first

# Public / private (applies an S3 bucket policy)
zcp object-storage bucket set-acl <storage> <bucket> --acl public-read
zcp object-storage bucket set-acl <storage> <bucket> --acl private

# Versioning
zcp object-storage bucket versioning enable  <storage> <bucket>
zcp object-storage bucket versioning suspend <storage> <bucket>
zcp object-storage bucket versioning status  <storage> <bucket>

# Raw S3 bucket policy (fine-grained access)
zcp object-storage bucket policy get    <storage> <bucket>            # -o yaml supported
zcp object-storage bucket policy set    <storage> <bucket> --file policy.json
zcp object-storage bucket policy delete <storage> <bucket>

# Tags
zcp object-storage bucket tag set    <storage> <bucket> --tag env=prod --tag team=data
zcp object-storage bucket tag get    <storage> <bucket>
zcp object-storage bucket tag delete <storage> <bucket>

# Default encryption (SSE-S3) - 'enable' is refused, see the warning below
zcp object-storage bucket encryption status  <storage> <bucket>
zcp object-storage bucket encryption disable <storage> <bucket>

# Lifecycle (auto-expire)
zcp object-storage bucket lifecycle expire <storage> <bucket> --days 30 [--prefix logs/]
zcp object-storage bucket lifecycle expire <storage> <bucket> --noncurrent-days 7 --abort-multipart-days 3
zcp object-storage bucket lifecycle get    <storage> <bucket>          # -o yaml supported
zcp object-storage bucket lifecycle delete <storage> <bucket>

# CORS (browser apps)
zcp object-storage bucket cors set    <storage> <bucket> --origin '*' --method GET --method PUT --max-age 3600
zcp object-storage bucket cors get    <storage> <bucket>
zcp object-storage bucket cors delete <storage> <bucket>

# Incomplete multipart uploads (storage held by failed large uploads)
zcp object-storage bucket uploads list  <storage> <bucket>
zcp object-storage bucket uploads abort <storage> <bucket> <key>

set-acl values: private, public-read, public-read-write. Lifecycle accepts --days (current versions), --noncurrent-days (old versions), and --abort-multipart-days; combine with --prefix to scope to a key prefix.

Object

zcp object-storage object list  <storage> <bucket>
zcp object-storage object stat  <storage> <bucket> <key>          # size, content-type, ETag, metadata
zcp object-storage object put   <storage> <bucket> ./file.bin --key data/file.bin \
    --content-type application/octet-stream --metadata owner=alice
zcp object-storage object download <storage> <bucket> <key> --dest ./file.bin
zcp object-storage object delete   <storage> <bucket> <key> -y

# Shareable URLs (no credentials needed by the recipient)
zcp object-storage object url     <storage> <bucket> <key> --expires 24h   # download link
zcp object-storage object put-url <storage> <bucket> <key> --expires 30m   # upload link (curl -T)

# Server-side copy / move (no download/upload round-trip)
zcp object-storage object copy <storage> <src-bucket> <src-key> <dst-bucket> <dst-key>
zcp object-storage object move <storage> <src-bucket> <src-key> <dst-bucket> <dst-key>

# Tags
zcp object-storage object tag set <storage> <bucket> <key> --tag kind=report

# Versioning workflows (require: bucket versioning enable)
zcp object-storage object versions <storage> <bucket> [--prefix p/]        # list versions + delete markers
zcp object-storage object download <storage> <bucket> <key> --version-id <id>
zcp object-storage object delete   <storage> <bucket> <key> --version-id <id>
zcp object-storage object restore  <storage> <bucket> <key>                # undelete (remove latest delete marker)

Flag	Commands	Description
--key	put	Remote object key (defaults to the local filename)
--content-type	put	Content-Type (auto-detected from extension if omitted)
--metadata k=v	put	User metadata (x-amz-meta-*), repeatable
--dest	download	Local file or directory
--version-id	download, delete, stat	Target a specific object version
--expires	url, put-url	Link lifetime (e.g. 30m, 24h; max 168h/7 days)
--prefix	versions	Restrict to a key prefix

Tip

Presigned URLs (object url / object put-url) let you hand a single object to someone without sharing credentials or making the whole bucket public. The link works until it expires (max 7 days), even on a private bucket.

Default encryption is not available

The storage gateway has no encryption key backend yet, so default bucket encryption (SSE-S3) does not work in any interface. Setting it makes every subsequent upload to that bucket fail with InvalidArgument until the setting is removed, which is why zcp refuses the command outright:

zcp object-storage bucket encryption enable <storage> <bucket>

Error: bucket encryption enable is not supported on this platform yet: the object storage
gateway has no encryption key backend, and enabling default SSE-S3 makes every upload to the
bucket fail with InvalidArgument until it is disabled again.

The S3 API accepts PutBucketEncryption without that guardrail, so an SDK or aws s3api put-bucket-encryption will break the bucket without warning. Do not set it. If a bucket is already affected, inspect and clear it:

zcp object-storage bucket encryption status  <storage> <bucket>
zcp object-storage bucket encryption disable <storage> <bucket>

Server-side encryption remains unavailable. Encrypt on the client before upload. Back Up Vaultwarden to Object Storage with restic walks through doing that with restic, which encrypts and authenticates every object before it leaves the machine.

Not yet in the CLI

• Object Lock (WORM): enable it when creating a bucket in the portal, or directly against the S3 endpoint with an SDK. CLI support is planned.
• Auto-scaling the instance: use the portal.
• Default encryption (SSE-S3): blocked platform-wide, see above.

Everything else listed in the matrix above is fully supported in zcp today.