Skip to navigation
Command reference

files Commands

View as Markdown

Manage files

Output formatting flags (--json, --jq, and --template) are documented once in Output Formatting and are omitted from the tables below.

bctrl files content

Download the bytes for one file.

bctrl files content <fileId> [flags]
FlagDescription
--query <json>Query object: inline JSON, @file, or - for stdin
--params <json>Alias for —query
--run-id <value>Query parameter runId
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)
--out <path>Write binary content to a file, or - for stdout

bctrl files delete

Delete one uploaded or collected file.

bctrl files delete <fileId> [flags]
FlagDescription
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)
--idempotency-key <key>Retry key for this operation
--yesConfirm this destructive operation

bctrl files get

Get one file metadata record using the canonical file resource.

bctrl files get <fileId> [flags]
FlagDescription
--query <json>Query object: inline JSON, @file, or - for stdin
--params <json>Alias for —query
--run-id <value>Query parameter runId
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)

bctrl files list

List the canonical durable File resource. Runtime file endpoints operate on a live machine disk: collect turns a machine file into a durable File, while stage performs the reverse. Use source, type, runId, runtimeId, path, prefix, and createdAfter filters here.

bctrl files list [flags]
FlagDescription
--query <json>Query object: inline JSON, @file, or - for stdin
--params <json>Alias for —query
--space-id <value>Query parameter spaceId
--source <value>Query parameter source
--path <value>Query parameter path
--prefix <value>Query parameter prefix
--q <value>Query parameter q
--run-id <value>Query parameter runId
--runtime-id <value>Query parameter runtimeId
--type <value>Query parameter type
--created-after <value>Query parameter createdAfter
--include <value>Query parameter include
--cursor <value>Query parameter cursor
--order <value>Query parameter order
--limit <value>Query parameter limit
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)

bctrl files update

Update one file display name or caller-owned metadata.

bctrl files update <fileId> [flags]
FlagDescription
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)
--idempotency-key <key>Retry key for this operation
--body <json>Request body: inline JSON, @file, or - for stdin

bctrl files upload

Upload a file into a space and return the canonical file resource.

bctrl files upload [flags]
FlagDescription
--query <json>Query object: inline JSON, @file, or - for stdin
--params <json>Alias for —query
--space-id <value>Query parameter spaceId
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)
--idempotency-key <key>Retry key for this operation
--file <path>Upload a local file, or - for binary stdin
--fields <json>Multipart fields: inline JSON, @file, or - for stdin