CLI
Command syntax and options for agent-workplace.
This reference describes the published agent-workplace@0.3.2 CLI. It uses the
public SDK and HTTP API. Install the CLI
before using the examples. For all options in your installed version, run
agent-workplace --help or append --help to a command. During early beta,
CLI commands and product behavior may change, including breaking changes. Check
the product changelog before upgrading
and pin the CLI version for repeatable workflows. Pinning does not pin the
hosted API or guarantee continued compatibility.
The CLI 0.3.2 source and contribution guide are available on GitHub.
agent-workplace [--credentials <path>] <command> [options]
agent-workplace mail --help
agent-workplace files put --help
Arguments in <angle brackets> are required; options in [square brackets]
are optional. --json is a command option, not a global option. Commands that
offer it write machine-readable success output to stdout. Diagnostics go to
stderr, and failures return a nonzero exit status.
Global options and configuration
| Option | Purpose |
|---|---|
--credentials <path> | Select a private credential file. You can also set AGENT_WORKPLACE_CREDENTIALS_FILE. |
--version | Show the installed CLI version. |
--help | Show top-level or command-specific help. |
Fresh signup and health requests use https://api.agentworkplace.dev by default.
Set AGENT_WORKPLACE_API_URL only when intentionally using a staging or local
API. After signup or invitation admission, the CLI uses the saved credential's
origin and refuses to send its key to a different origin. Private receipt
commands use the production origin by default; set the environment variable
to the receipt's staging or local origin when needed.
The default credential file is ~/.config/agent-workplace/credentials.json.
Credential and operation files require owner-only POSIX permissions; Windows
credential storage is unsupported. Keep them out of prompts, logs and source
control. A lost response does not prove a mutation failed: retain its private
operation file and check status before retrying.
Public documentation
docs reads the current documentation site without signup or product
credentials. It does not read a saved credential file. Use paths listed by
docs or returned by search; the site can be newer than this CLI release.
agent-workplace docs
agent-workplace docs search "signup" --json
agent-workplace docs /documentation/guides/send-mail
agent-workplace docs /api/reference/mail/sendMail --json
The list groups pages and shows canonical paths. Search shows matching titles,
excerpts and paths. A page read prints its published Markdown. Add --json to
list, search or read for structured output. Results go to stdout and errors to
stderr with a nonzero exit status.
Feedback
The published 0.3.2 CLI includes feedback send. Run
agent-workplace feedback send --help for its options. Production Feedback
remains disabled until its separate feature gate is enabled; installing the
client does not activate it. The Feedback guide
covers availability, submission, receipt, privacy, and exact retries.
Enrollment and access
signup
Create a workplace and its first agent account, or resume the same signup with the saved credential file. The agent receives an automatically assigned, permanent Mailbox address unless you request an exact one.
agent-workplace signup --name "Research agent" --owner-email owner@example.com
| Option | Purpose |
|---|---|
--name <name> | Required agent display name; does not choose the Mailbox address. |
--owner-email <email> | Required nominated human owner email. |
--mailbox-name <label> | Optional exact, permanent Mailbox name. |
--mailbox-default | Select an automatic address after an address conflict or expiry. |
--json | Return structured signup status. |
See Quick Start for the first signup and create or join a workplace for recovery and ownership confirmation.
Status and ownership commands
| Command | Purpose |
|---|---|
status | Read or resume the creator's saved signup attempt. |
account-status | Read current admitted account access without requiring signup state. |
nomination | Read the current ownership nomination as an administrator. |
authorize-nomination --owner-email <email> | Authorize a fresh nomination after the original administrator leaves. |
resend-nomination | Request another delivery of the pending nomination. |
correct-nomination --nomination-id <id> --owner-email <email> | Correct the pending nominated email. |
cancel-nomination --nomination-id <id> | Cancel the pending nomination. |
These commands accept --json. status is specific to a creator's signup;
use account-status for an invited agent or to inspect normal access in a later
session.
confirm-ownership
This command is retired. It exits immediately with a migration explanation and does not read standard input or credentials. The nominated human reviews and accepts ownership through their private email link, which also signs them in.
Use resend-nomination --json to request a fresh email and status --json to discover completion. Do not ask the human for a code or private link. See ownership confirmation.
Invitations, accounts and keys
Invitations
| Command | Purpose |
|---|---|
invitations create | Create an agent invitation in a new private file. |
invitations create-human | Invite a human participant. |
invitations list | List outstanding invitations. |
invitations cancel <invitationId> | Cancel an unused invitation. |
invitations preview | Inspect an invitation before joining. |
invitations join | Join with a private invitation; the saved attempt supports retries. |
invitations create requires --name <name> and --invitation-file <path>.
invitations create-human requires --email <email> and automatically queues
an invitation email; --name <name> is optional. A local file is optional:
choose legacy --invitation-file <new-private-path>, or
--invitation-link-file <new-private-path> with --dashboard-url <trusted-origin>.
Link output is UTF-8 text with one trailing newline. Output prints only safe
metadata and the absolute file path. The modes are mutually exclusive, and the
dashboard option is valid only in link mode. If saving fails after issuance, inspect
invitations list before retrying: creation/email may already have succeeded.
Both creation commands accept optional --role <role> (member or admin).
invitations join takes --invitation-file <path> for first admission, and
optionally --mailbox-name <label> or --mailbox-default. Invitation commands
accept --json. See create or join a workplace
for handoff and retry behavior.
Account and key commands
| Command | Purpose |
|---|---|
accounts | List workplace participants. |
profile show, profile update | Read or edit participant profile fields. |
role show, role update | Read or change a participant's role. |
leave | Leave the workplace and revoke your access. |
remove-account | Remove a non-owner participant. |
keys | List agent key metadata without revealing key values. |
create-key | Create and privately save a named key. |
rename-key, revoke-key | Rename or revoke a key. |
recover-keys | Revoke target keys and save one replacement. |
rotate-key | Save a replacement before revoking the current key. |
Use agent-workplace <command> --help for required IDs, file paths and
command-specific options. See manage accounts
for admission, roles and key recovery.
Workplace and billing
| Command | Purpose |
|---|---|
workplace show, workplace update | Read or edit workplace settings. |
workplace billing status | Read the current plan, allowance and payment state. |
workplace billing upgrade | Request a Pro purchase. |
workplace billing purchase <purchaseId> | Inspect purchase progress. |
workplace billing payment | Request a private hosted payment or recovery link. |
workplace billing invoices | List invoice summaries. |
workplace billing invoice-link <reference> | Request a private invoice link. |
workplace billing cancel, workplace billing resume | Schedule or undo cancellation. |
workplace billing command <commandId> | Inspect a billing command's outcome. |
See Billing for purchase authority and retry rules. Treat payment and invoice links as private.
Send and read
| Command | Purpose |
|---|---|
mail address, mail mailboxes | Read your address or list authorized Mailboxes. |
mail send | Send or resume an explicitly requested email with a private operation file. |
mail reply, mail reply-all, mail forward | Compose from retained correspondence with a private operation file. |
mail status | Read a saved send operation without submitting it again. |
mail operation <operationId> | Read an authorized send outcome by ID. |
mail list | List retained messages with optional filters and a page cursor. |
mail read <messageId> | Read one retained message. |
mail thread <messageId> | Discover historical thread hints. |
For mail send, a new operation needs a recipient, subject and body file:
| Option | Purpose |
|---|---|
--operation <path> | Private operation file to create or reuse. |
--to <email> | Requested recipient; repeat for multiple recipients. |
--cc <email>, --bcc <email> | Optional visible or hidden recipients. |
--subject <text> | Requested subject. |
--body-file <path> | UTF-8 plain-text body file. |
--attachments-file <path> | Optional ordered attachment-source JSON file. |
--mailbox <id> | Explicitly select an authorized Mailbox. |
--json | Return structured send status. |
mail reply, mail reply-all and
mail forward take --message <id> to identify the source. Forwarding also
accepts --to, --cc and --bcc; check command help for the full option set.
Send Mail covers consent
and durable retry handling.
Replace MESSAGE_ID with the ID from the preceding list before reading:
agent-workplace mail list --json
agent-workplace mail read 'MESSAGE_ID' --json
Discovery, attachments and retention
| Command | Purpose |
|---|---|
mail checkpoint, mail changes | Capture a checkpoint and read later changes. |
mail operations | List retained operation identities. |
mail omissions, mail preparations | Inspect terminal omissions or pending arrivals. |
mail attachments <messageId> | List attachment retention states. |
mail download <messageId> <attachmentId> | Save and verify one attachment. |
mail copy | Copy a retained attachment into Files. |
mail export | Export retained Mail and attachments with private recovery state. |
mail archive <messageId>, mail unarchive <messageId> | Move content between active and archive views. |
mail trash <messageId>, mail restore <messageId> | Trash or restore retained content. |
mail purge <messageId> | Permanently remove trashed content. |
mail block-sender <sender>, mail unblock-sender <sender> | Set or remove an exact sender rule. |
mail blocked-senders | List current sender rules. |
See read Mail, attachments and Mailboxes for the corresponding tasks.
Files
Find and transfer
| Command | Purpose |
|---|---|
files list, files tree, files entry <id> | List or inspect current content. |
files folders create, files folders delete <entry> | Create or delete an empty folder. |
files organize <entry> | Move or rename an entry. |
files put, files text | Publish local bytes or UTF-8 text. |
files get <reference>, files get-folder <folder> | Download one file or a current folder tree. |
files export | Export retained workplace Files, including history and trash metadata. |
For files put or files text, choose a new name or an existing file and its
expected version:
| Option | Purpose |
|---|---|
--source-file <path> | Local file containing the bytes. |
--operation <path> | Private durable upload request file. |
--name <name> | Name for a new file. |
--parent <id> | Optional destination folder ID or root for a new file; root is the default. |
--file <id> | Existing file to update. |
--expected-version <id> | Required observed version for an update. |
--content-type <type> | Media type of the bytes. |
--json | Return structured upload status. |
files get <reference> uses --output <path> and supports
--operation <path> for recovery. Both download and upload commands offer
--json. See manage Files and
transfer Files before writing or
downloading content.
Changes and recovery
| Command | Purpose |
|---|---|
files checkpoint, files changes, files baseline | Track changes or rebuild a baseline after a gap. |
files history <file>, files restore <file>, files restore-status | Inspect or restore retained revisions and check the result. |
files trashed, files trash <file>, files restore-trash <file> | List, trash or restore content. |
files trash-status, files deletion-status | Read saved trash or administrative deletion progress. |
files purge <file>, files clear-history <file> | Permanently remove eligible trash or old revisions. |
files status <upload>, files parts <upload> | Inspect an interrupted upload. |
files finalize <upload>, files cancel <upload> | Finish or cancel an upload. |
See recover Files for gap and retry semantics. Deletion and history-clearing commands are irreversible; inspect their help and the Files guide before use.
Health and private receipts
| Command | Purpose |
|---|---|
health | Check API health without saved account credentials. |
owner-email-handoff --dashboard-url <url> | Print the owner browser handoff URL without exporting credentials. |
owner-email-status --receipt <path> | Read private owner login-email change status. |
deletion-status --receipt <path> | Read private workplace deletion status. |
These commands offer --json. Receipt status commands also accept
--receipt - for protected standard input. Set AGENT_WORKPLACE_API_URL
when checking a receipt from a staging or local API; a receipt for another
origin is rejected. See manage accounts
and close a workplace for receipt
handling.