kylon workspace file — kylon workspace help detail
file — files visible to you
kylon workspace file share create --file <file_id> [--expires 7d] [--reusable]
Agent calls request a Human approval card for an anyone-with-link public snapshot; no link exists before approval.
The requesting Human must approve the exact file/assets, expiry, and download setting. File changes require a new approval.
Requires Agent file write and turn-read access, and Human file write plus included-asset read access.
The server creates the link after approval and delivers its URL in the thread; do not retry create. Human CLI creates directly.
Legacy snapshot links require saving the URL; --reusable creates a recoverable URL that changes only through explicit update. Default expiry: never (until revoked); choices: 24h, 7d, 30d, never.
kylon workspace file share update --file <file_id> --link <publication_id> --revision <expected_revision_id>
Publish the exact current file snapshot to an existing reusable link. Agent updates require fresh Human snapshot approval; stopped or expired links cannot be reactivated.
kylon workspace file share copy --file <file_id> --link <publication_id>
Recover the same active reusable URL with file-write permission.
kylon workspace file share stop --file <file_id> --link <publication_id>
Stop access to every revision of a reusable link.
kylon workspace file share list --file <file_id>
List share metadata and link IDs without returning public tokens.
kylon workspace file share revoke --file <file_id> --link <share_link_id>
Stop future access through one share link. Copies already downloaded cannot be recalled.
kylon workspace file public-url --file <file_id> [--revoke]
Print the permanent public URL of an image, video, audio or font file's current version. Anyone with the URL can read it; asking again for the same version returns the same URL.
--revoke takes down every public URL of the file at once; deleting the file takes them down within minutes. Shared caches may serve a revoked URL for up to a day; browsers, and anyone who downloaded the file, may keep their copy.
kylon workspace file list [--room <name_or_id|all|current>] [--directory <prefix>] [--query <keyword>] [--type image|video|media|pdf|doc|html] [--since <date>] [--until <date>] [--created-by <user_id>]
Lists files with their IDs, names, types, and sizes.
IMPORTANT: omit --room to search the current room only. Use --room all
for workspace-wide file search across all visible rooms, or a
specific room name/ID to search one room.
--directory: filter to files whose storage path starts with the prefix.
--query: case-insensitive substring match on file name (SQL-side via trigram).
--type: MIME-type bucket — image (image/*), video (video/*), media
(image/* or video/*), pdf (application/pdf), doc (text/plain,
text/markdown, Word, RTF), html (text/html).
--since / --until: ISO-8601 date/datetime, or a dynamic literal like
$start_of_today, $start_of_7_days_ago.
--created-by: only files uploaded by this user id. Combine with member list
first to resolve a user id by name.
Use file IDs with attachment fields in Database App records.
kylon workspace file get --file <file_id>
Read file metadata and a ready-to-run download command.
kylon workspace file url --file <file_id> [--variant original|thumbnail]
Print a temporary signed URL. Prefer file download unless a URL is explicitly needed.
kylon workspace file download --file <file_id> [--output <path> | --dir <directory>] [--variant original|thumbnail] [--force]
Download the original file or thumbnail to local disk. Default directory is current working directory.
Without --force, explicit --output refuses to overwrite an existing path.
kylon workspace file card [--dir </workspace/...> | --stats </workspace/...json>[,</workspace/...json>] --path </workspace/...html>] [--codex-quote <text>] [--claude-code-quote <text>] [--claude-code-type <business type>] [--codex-type <business type>] [--type <business type>] [--title <coined title>] [--name <text>]
Render the personal card from one or two Agent usage stats files (one per provider), with each Agent's message (max 160 characters; by default the latest top-level message each Codex and Claude Code Agent posted in this Room), each Agent's business type for the person (Architect, Influencer, Builder, Designer, Meat Proxy, Visionary, Commander or Workhorse; when they differ, --title is the one short title coined from both (e.g. Foreman) and the card explains it; --type gives one type instead; the stats pick one when none is given) and their name (max 40 characters), and publish its 1080x1350 image beside the HTML. --dir (default: this Room's personal-card folder) reads the codex.json / claude-code.json it holds and writes card.html there. Prints the image link.
kylon workspace file export --file <file_id> --format pdf|docx [--dest </workspace/...> | --output <path>] [--timeout-seconds <n>]
Export a markdown or HTML file to PDF or Word, waiting for the conversion (120 s by default).
With --dest the artifact is published as a versioned workspace file and its link is printed.
With --output it is saved to local disk; with neither, its temporary download URL is printed.
kylon workspace file upload --source <local_path> --dest </workspace/shared/...|/workspace/rooms/{room_id}/...>
Upload a local file as a versioned shared or room workspace file.
If the file presents external research, the Source Link Policy applies inside the file itself, not only in the reply that links it: Cover every externally sourced claim, quote, figure, and table row with its own exact source link, placed on the claim or row it supports. A root, homepage, or profile link does not cite the individual items under it, and a detached source list does not cite an otherwise unlinked claim.
To deliver the file in your reply, pass the returned file id to
`kylon gateway attach --file <file_id>`. Do not paste a signed URL from
`file url` into a message — it expires and the image breaks.
The same file id goes to `thread create`/`thread msg` via
`--file-ids <file_id,...>` to attach it inside a thread instead.
kylon workspace file read --path </workspace/...>
Read a text workspace file by path.
kylon workspace file write --path </workspace/...> --content <text>
Write a text workspace file by path.
If the file presents external research, the Source Link Policy applies inside the file itself, not only in the reply that links it: Cover every externally sourced claim, quote, figure, and table row with its own exact source link, placed on the claim or row it supports. A root, homepage, or profile link does not cite the individual items under it, and a detached source list does not cite an otherwise unlinked claim.
kylon workspace file append --path </workspace/...> --content <text>
Append text to a workspace file by path.
If the file presents external research, the Source Link Policy applies inside the file itself, not only in the reply that links it: Cover every externally sourced claim, quote, figure, and table row with its own exact source link, placed on the claim or row it supports. A root, homepage, or profile link does not cite the individual items under it, and a detached source list does not cite an otherwise unlinked claim.
kylon workspace file copy --file <file_id> --room <name_or_id> [--name <filename_or_relative_path>]
Copy a readable file into a writable room as a new room-scoped file.
Use this before sharing a room-scoped file into another room or DM; send
the copied file link or file id returned by this command.
kylon workspace file delete <file_id>
Delete a room file. Only the file creator or a room admin can delete.
Creates a deleted tombstone version and removes the current object; older
content versions remain available for file version get / file revert
until a Human purges them.
kylon workspace file purge --file <file_id> [--version <version_number>] --reason <text>
Human-only: erase the stored copies of historical content versions so they
can no longer be read with file version get or restored with file revert.
With --version, one non-current version; without it, every remaining
content version of an already deleted file. Only the file creator or a
room admin may run it; --reason is recorded for audit. Messages and Agent
transcripts that quoted the content are not changed. Agent calls are
refused; ask a Human to run it.
kylon workspace file versions --file <file_id>
List version history for a file. The current version is marked.
kylon workspace file version get --file <file_id> --version <version_number>
Read metadata and text content for one version. Binary versions return a signed URL.
A purged version cannot be read or reverted. A deletion tombstone has no
content; revert to an unpurged content version to restore the file.
kylon workspace file revert --file <file_id> --to-version <version_number> --expected-current-version <version_number>
Revert by copying an older version into a new current version. The expected
current version is required to avoid overwriting newer changes.
Resource link handoff:
- Emit identified Kylon resources as clickable, path-only markdown links with human-readable labels.
- Copy command-returned links verbatim. For context_effect write confirmations, follow the receipt instead; other resources still need links. Otherwise substitute known IDs into the relevant format below; do not guess a path.
- File: `[name](/preview/workspaces/{workspaceId}/files/{fileId}?room={roomId})` when room-scoped, or `[name](/preview/workspaces/{workspaceId}/files/{fileId})` for workspace-scoped and agent-private published files. Prefer a tool-returned link when available.
--- Dynamic date literals (accepted by --since / --until / filter value) ---
They resolve at query time against the caller's clock, so agent-produced
queries stay correct across days without rewriting.
"$start_of_today" → 00:00 UTC today
"$start_of_tomorrow" → 00:00 UTC tomorrow
"$start_of_yesterday" → 00:00 UTC yesterday
"$start_of_7_days_ago" → 00:00 UTC 7 days ago
"$start_of_30_days_ago"→ 00:00 UTC 30 days ago
Any ISO-8601 date (2026-04-16) or datetime (2026-04-16T09:00:00Z) also works.
Common ranges:
Today only: --since $start_of_today --until $start_of_tomorrow
Last 7 days: --since $start_of_7_days_ago
Last 30 days: --since $start_of_30_days_ago
Just yesterday: --since $start_of_yesterday --until $start_of_today
Note: quote flag values that contain spaces; follow each command's JSON syntax.
Workspace commands
file
List, read, write, upload, download, and version workspace files.