bucket key

An access key reaches one bucket and no other. read-write can read, upload and delete files, and read-only can read and list them.

The secret is shown once, in the result of bucket key create, and no command returns it again, so a lost secret means a new key. There is no rotation: replacing a key means creating a new one, moving the clients to it, and deleting the old one. A deleted key can keep working for up to 15 minutes.

The secret is printed on stdout, so it lands wherever the command ran: a terminal's scrollback, a CI log, an agent's transcript. An agent driving the CLI hands bucket key create to the person to run in their own terminal. To give the key to an application, put the values in a .env file and run outplane env push, rather than pasting the secret into env set, which leaves it in shell history. The variable names are on the console's Buckets page.

bucket key list

List the access keys on a bucket.

Usage

outplane bucket key list <BUCKET>

Arguments

Output

Examples

Which keys reach a bucket

outplane bucket key list uploads

Find the id to delete

outplane bucket key list uploads --json --fields name,accessKeyId,permission

{
  "items": [
    {
      "accessKeyId": "<ACCESS_KEY_ID>",
      "name": "web",
      "permission": "read-write"
    }
  ],
  "total": 1,
  "truncated": false
}

The same list as a table, in a pipe

outplane bucket key list uploads -o text

What to Know

• A secret never appears here and cannot be read again, by this or any other command.
• Names are not enforced unique, and accessKeyId is what to store.
• An empty list is not an error. A new bucket has no key.

Errors

Beyond 0 for success, this command exits with:

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.

bucket key create

Add an access key to a bucket, showing its secret once.

Usage

outplane bucket key create <BUCKET> <NAME> [flags]

Arguments

Flags

This command does not accept --fields. Every other global flag applies.

Output

Examples

Check the request without creating a key

outplane bucket key create uploads web --permission read-write --dry-run --json

{
  "accessKeyId": null,
  "changed": false,
  "name": "web",
  "permission": "read-write",
  "secretAccessKey": null
}

A key an application can read and write with

outplane bucket key create uploads web --permission read-write

A key that can only read, with the whole result as JSON

outplane bucket key create uploads reports --permission read-only --json

{
  "accessKeyId": "<ACCESS_KEY_ID>",
  "bucketName": "uploads-<SUFFIX>",
  "changed": true,
  "endpoint": "<ENDPOINT>",
  "name": "reports",
  "permission": "read-only",
  "region": "auto",
  "secretAccessKey": "<SECRET_ACCESS_KEY>"
}

What to Know

• The secret appears once, in this result, in every format and under --quiet. No other command returns it and it cannot be read again.
• The secret is on stdout, so it lands in the record of whatever ran this command: a terminal's scrollback, a CI log, an agent's transcript. That makes this a command for a person at their own terminal when an agent is driving.
• outplane env push reads an application's values from a file, which keeps them out of shell history and out of argv.
• Clients use bucketName with virtual-hosted addressing and the region auto. Path-style requests fail.
• A timeout, a dropped connection, a proxy's reply or a success with no secret in it can leave a key nobody has the secret of. retryable is false in those cases, because a retry makes another key, and bucket key list shows what exists. A 5xx the API wrote itself stays retryable.
• There is no rotation. Replacing a key means a new key, moving the clients to it, and then bucket key delete on the old one.
• --fields is refused with exit 2 before anything is sent, because narrowing the result could discard the only copy of the secret.

Errors

Beyond 0 for success, this command exits with:

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

bucket key delete

Remove an access key from a bucket.

Usage

outplane bucket key delete <BUCKET> <KEY> [flags]

Arguments

Flags

The global flags apply as well.

Output

Examples

See which key would go

outplane bucket key delete uploads web --dry-run

The confirmed form, which a human approves

outplane bucket key delete uploads web --yes --confirm-name web

Check what the name resolves to

outplane bucket key delete uploads web --dry-run --json

{
  "accessKeyId": "<ACCESS_KEY_ID>",
  "changed": false,
  "name": "web"
}

What to Know

• This command never prompts. Without confirmation it exits 4 and returns the command to replay in the error's confirm_command field, which names the key by its id.
• Under a detected agent harness it exits 4 even with both flags.
• The old secret can keep working for up to 15 minutes after this succeeds.
• Applications holding it are not updated.
• Deleting a key by name fails when two keys share it, with bucket.key_ambiguous. The id always works.
• bucket.key_not_found on a key that was just resolved can also mean its bucket went in that moment. bucket key list tells the two apart.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of confirmation.required, bucket.confirm_name_mismatch, bucket.key_not_found, bucket.key_ambiguous, 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.

Related