Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

tractorbeam workspace

The Tractorbeam API's workspace operations.

tractorbeam workspace <subcommand> [flags]

Shared flags

Every subcommand takes these flags.

Flag Description
--config <string> The Project’s tractorbeam.config.ts. Defaults to the one in the current directory or its nearest ancestor.
--workspace <string> Workspace name. Environment variable: TRACTORBEAM_WORKSPACE.
--origin <string> The Tractorbeam origin to call instead of the default, such as a proxy’s. Environment variable: TRACTORBEAM_ORIGIN.
--token <string> Access token. Defaults to the saved interactive session. Environment variable: TRACTORBEAM_TOKEN.

workspace list

Returns the active Workspaces of every WorkOS organization the authenticated user belongs to, oldest first. Each Workspace comes with its organization and the URL serving it. Answers at any host, and needs a Console sign-in but no Account permission.

tractorbeam workspace list [flags]

workspace create

Creates a Workspace in an existing Account or in a new one. Without account, the Workspace joins the Account of the Workspace whose host the request addresses. With account, at any host, it provisions the Account account describes, with this Workspace as its first, and invites the Account’s first manager. No Account is ever without a Workspace.

Only a credential with admin:create-account, issued for the configured provisioning organization, can provision an Account or set bucket: the Console session or API key of a member of the Tractorbeam team, or a service user of that organization. An App token can’t. Provisioning doesn’t grant customer access.

A retry with the same inputs, and the same idempotency-key if the first request sent one, returns the Workspace the first request created. A Workspace name already taken with other inputs returns 409.

tractorbeam workspace create [flags]
Flag Description
--workspace-name <string> The Workspace’s name. It never changes.
--display-name <string>
--hosting-model <TRACTORBEAM|CUSTOMER> Whose cloud holds the Workspace’s data and data plane.
--account <json> The Account to provision with this Workspace as its first. Absent, the Workspace joins the Account of the Workspace whose host the request addresses.
--organization-id <string>
--bucket <json> The bucket where the Workspace keeps everything it stores. Absent, the Workspace uses the bucket the deployment’s Workspaces share.
--json <json> The body’s fields as one JSON object. Flags given as well override its fields.

workspace get

Returns the Workspace whose host the request addresses, and whether its data plane is connected. An idle Workspace starts on its next request, and that request waits until the Workspace is ready. This operation answers at once and starts nothing: with it, a client can tell a starting Workspace from one slow to answer. Any principal of the Workspace’s organization can retrieve it; an App token can’t.

tractorbeam workspace get [flags]

workspace archive

Archives the Workspace whose host the request addresses, and returns it with status ARCHIVED. The Workspace keeps its name, storage roots, and identity configuration, but its data plane can no longer open a session and its App Routes stop serving. Archiving an archived Workspace returns it unchanged. Needs account:manage; an App token can’t archive a Workspace.

tractorbeam workspace archive [flags]

workspace get-limits

Returns the revision of its Account’s policy currently applying to the Workspace. Tractorbeam runtimes cache it, and keep their last known good revision while Tractorbeam is temporarily unavailable. Needs account:manage because the policy belongs to the Account.

tractorbeam workspace get-limits [flags]