bucket get

read onlyrepeatable

One bucket, and everything a client needs to reach it except a key: bucketName, the endpoint and the region. url is the bucket's own address, and it serves files by link only while the bucket is public.

Pass the bucket's name or id, not its bucketName. Matching is exact.

Usage

outplane bucket get <BUCKET>

Arguments

Argument	Type	Description
`BUCKET`	`string`	The bucket's name or id, not its bucketName. Required.

Output

Field	Type	Description
`id`	`string`
`name`	`string`	What the platform calls it, unique in the team.
`bucketName`	`string`	The name S3 clients use. It carries a suffix, so it differs from name.
`public`	`bool`	The setting last accepted: whether anyone with a file's link can read it. A change takes minutes to reach every request. Listing stays off either way.
`endpoint`	`string`	The S3 endpoint. Clients need virtual-hosted addressing; path-style requests fail.
`region`	`string`	The region clients sign with, always auto.
`url`	`string`	The bucket's own address. It serves a file without a signature only when the bucket is public, and after a change to private it can keep doing so for some minutes.
`createdAt`	`string \| null`	RFC 3339, UTC.

Examples

Show a bucket

outplane bucket get uploads

Read what a client needs, in a script

outplane bucket get uploads --json --fields bucketName,endpoint,region

{
  "bucketName": "uploads-<SUFFIX>",
  "endpoint": "<ENDPOINT>",
  "region": "auto"
}

See the whole record in a pipe

outplane bucket get uploads -o text

What to Know

There is no endpoint that takes a name, so this lists the team's buckets and matches. The cost is the same as bucket list.
Matching is exact, on the id first and then the name.
Clients use bucketName, not name, and the region auto.
Clients need virtual-hosted addressing, with bucketName in the host. Path-style requests fail.
url serves a file without a signature only when public is true. public is the setting last accepted, so after a change to private, url can keep serving files without a signature for some minutes.
A new bucket's address can take a few minutes to start working, for S3 clients as well as public links. A TLS error right after create means it is not ready yet.

Errors

Beyond 0 for success, this command exits with:

Exit	Kind	Meaning
`2`	`usage`	Invalid arguments, unknown flag, or client-side validation failure.
`3`	`auth`	Not authenticated, token revoked or expired, or forbidden for this team.
`5`	`not_found`	The named resource does not exist, or is not visible to this credential.
`8`	`upstream`	The Out Plane API returned a server error.

The code on the error object is one of bucket.not_found, usage.missing_argument, usage.empty_argument, context.no_team. Branch on that, or on the exit status. The message is prose and changes.