bucket create
Create a bucket, private unless told otherwise.
Creates a bucket, private unless --public is given. A short random suffix is added to the
name to make the address unique, and the result's bucketName is the name S3 clients use.
A new bucket's address can take a few minutes to start working, for S3 clients as well as
public links. A new bucket has no key, and
bucket key create makes one. A team can have up to 5 buckets on
every plan, and deleting one is the only way to make room.
Usage
outplane bucket create <NAME> [flags]Arguments
| Argument | Type | Description |
|---|---|---|
NAME | string | 3 to 38 lowercase letters, numbers and single hyphens. Required. Must match ^[a-z0-9][a-z0-9-]{1,36}[a-z0-9]$. |
Flags
| Flag | Type | Description |
|---|---|---|
--public | bool | Let anyone with a file's link read it. Private without this. |
The global flags apply as well.
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. |
changed | bool | False for a dry run, where what only the server decides is null. |
Examples
A private bucket
outplane bucket create uploadsA bucket whose files are served by link
outplane bucket create assets --publicCheck the request without creating anything
outplane bucket create uploads --dry-run --json{
"bucketName": null,
"changed": false,
"name": "uploads",
"public": false
}What to Know
- A bucket is private unless --public is given.
- 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.
- A new bucket has no key, and clients need one.
bucket key createmakes one and prints its secret on stdout, which makes it a command for a person at their own terminal when an agent is driving. - A name taken in the team is exit 6, bucket.name_taken.
- The number of buckets a team can have is fixed, the same on every plan. Reaching it is exit 7, bucket.limit_reached, and only deleting a bucket makes room.
- A team without an active subscription gets exit 7, bucket.subscription_inactive. Billing is in the console.
- A timeout can still finish on the server, and
bucket listsays whether it did. Running this again after one that finished is exit 6.
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. |
6 | conflict | The resource already exists, or a concurrent change won. |
7 | quota | Plan limit reached or payment required. Not a rate limit; retrying will not help. |
8 | upstream | The Out Plane API returned a server error. |
124 | timeout | A client-side deadline expired. The server operation may still be running. |
The code on the error object is one of bucket.name_invalid, bucket.name_taken, bucket.limit_reached, bucket.subscription_inactive, usage.missing_argument, usage.empty_argument, context.no_team. Branch on that, or on the exit status. The message is prose and changes.