Univer Workspace CLI Core
Use uvw for remote Workspace content. If it is unavailable, stop and report that
the Workspace CLI is not installed. Do not substitute a local office writer because that bypasses
the remote Worktree and review lifecycle.
Read a Sheet
To understand a Sheet Unit, run uvw outline first. Zoom into a region or table with
--at <ref> from the map, locate values with uvw find, and read exact values with
uvw read --json. Run every printed continuation until none is printed. Do not scan a
Sheet with execute or treat one read page as the whole range. uvw skills read sheet references/reading.md lists every option.
Read a file from its link
When the user gives you a file link (<origin>/nodes/<node-id>), pass the link as --unit with
--trunk. outline, read, find, inspect, and screenshot accept it and resolve it to the Unit:
uvw outline --unit <file-link> --trunk
uvw read <range> --unit <file-link> --trunk --json
The output carries the Unit ID. This reads any file the session can read, including a file that
another user or agent shared with Link Sharing. You do not need to own the file or know its
repository. The commands still need a session, so sign in first, or continue as a guest agent when
that path applies. uvw share <file-link> is for the owner only, so a FORBIDDEN answer there does
not mean the file cannot be read.
Bind shared operations to the CLI
Other Skills name operations without uvw. Each is the uvw command of the same name, with flags defined by uvw <command> --help. Load a Skill with uvw skills get <name> and a reference with uvw skills read <name> <path>. Use uvw skills get <name> --full only when all references are needed; uvw skills path <name> --json locates installed files.
For Sheet read, the shared content modes map to CLI options. Omit content flags for both, use --values for display, --formulas for formula, --styles for style, and --formulas --styles for formula+style. Request typed stored values with --json. For find, repeat --sheet <name> for multiple sheets.
For local inputs, output paths, structured JSON, overwrite controls, browser setup, and file-backed sources, read CLI files and sources. It covers Office exchange, screenshots and PDFs, Slide SVG assets and resources, Typst bundles, Markdown maps and assets, Blob transfer, and HTML View sources.
SVG resources
When a Unit needs icons, logos, emoji, or illustrations, use the built-in SVG resource library:
uvw resources registries
uvw resources find <query> [<query>...]
uvw resources export <handle> [<handle>...] --out <directory>
Concepts
Understand these identities before running a mutation:
- Workspace origin: the remote Workspace service address of the user's own deployment.
Point the CLI at it with
uvw config set workspace.origin <origin>before connecting. - Space (a repository): the container whose visible tree is made of Nodes. A Team Space is named
<owner>/<slug>; every Personal Space is<owner>/personal. Pass that name as-R <owner>/<slug>(or setUVW_REPO); a Space ID, a Workspace URL, or a bare slug that uniquely matchesuvw repo listis accepted wherever a repository is expected. Unknown or ambiguous slugs require owner/slug; the error lists matching candidates. A Team Space created before slugs existed may have no name; use its Space ID. - Personal Space: the authenticated user's own Space. Files here are personal Workspace files.
A Personal Space is not a Worktree. Its repository name is
<username>/personal. - Team Space: a Space shared by a team. Access depends on current team membership and role.
- Issue: a Team Space discussion item addressed by Space and number (
#12), with a Markdown body, comments, labels, assignees, and referenced Nodes. Personal Spaces have no Issues. An Issue is a request, not a Worktree: reading or commenting on it never changes Space files. - Node: one tree position addressed by
nodeId. Every Node may have children. A pure organizational Node hasresource: null; a Node with a Resource may still have children. - Resource: the product content identity attached to a Node, discriminated by
kind. - Univer Resource:
kind: "univer", with one Sheet, Doc, Slide, Base, or BoardunitType. Use itsresourceIdto add existing editable content to a Worktree. - Blob Resource:
kind: "blob", with MIME, byte size, and availability but nounitTypeorunitId. Upload/download it directly; never add it to a Worktree. - Unit: the Collaboration content identity inside one Worktree. Use its
unitIdfor execute, inspect, screenshot, export, snapshot, and changeset operations. - Worktree: one task's isolated Agent workspace and draft/review boundary. Changes remain
isolated from the normal Space file until the Worktree is merged. The CLI calls it a pull
request (
uvw pr ...);uvw worktree ...is an equivalent spelling with the same options and output. This Skill usespr. A Team Worktree shares its#Nnumber sequence with the Space's Issues; a Worktree created before numbering existed hasnumber: nulland is addressed by itsid. - User-scoped Worktree: a private Worktree owned by the authenticated user, created with
-R <username>/personal. It can contain Units the user may edit from Personal or Team Spaces. It is not a Personal Space. - Space-scoped Worktree: a Worktree belonging to one Team Space, created with
-R <owner>/<slug>. It can contain only Units from that Space and may be private or visible to that Space. - Worktree-local Unit: a new Unit created inside a Worktree. The server allocates its
unitId,resourceId, andnodeId; merge activates the target Node/Resource.
Never interchange spaceId, nodeId, resourceId, unitId, Worktree id, pull request number, or
display name. Content commands (execute, inspect, screenshot, unit, import, export, ...) take
--worktree <id>: the id field of uvw pr view <n> -R <repo> --json id, not the #N number.
Use display names and path only for discovery and disambiguation; use stable ids for commands.
space browse and space find discover Nodes and Resources before they enter a Worktree. unit list only lists
Units already staged in one explicit Worktree. The separate resources command is an SVG asset
catalog, not Workspace file discovery.
Filter discovery by Resource kind and, independently, Univer Unit type:
uvw space browse <space-id> --resource-kind blob --json
uvw space find <name> --space <space-id> --resource-kind univer --unit-type doc --json
uvw space browse <space-id> --resource-kind none --json
--unit-type may be combined only with --resource-kind univer. Filters change returned results,
not recursive reachability; a Blob Resource Node may still have children.
Blob files
For original-file upload, download and replacement, read the Blob Skill
with uvw skills get blob.
HTML Views
For live HTML pages backed by Sheet data, read the HTML View Skill
with uvw skills get html-view.
Manage Space Nodes
Create a root organizational Node by naming the target Space:
uvw space node create \
<space-id> --name <node-name> --json
Create a direct child by passing the stable Node ID returned by the first command. A Resource Node may also be the parent when its capabilities allow child creation:
uvw space node create \
<space-id> --name <child-node-name> --parent <node-id> --json
Use that returned Node ID as --parent <node-id> when creating a Unit at that location. Do not
derive a parent from a display path or Node name.
Node creation is a direct Space write. It is not isolated in a Worktree, and Worktree
discard cannot undo it. The first version is non-idempotent: if the command reports
workspace-result-unknown, the Node may already exist. Do not retry blindly. First run
space browse <space-id> --parent <parent-node-id> --json, or omit --parent when the target was
the Space root, then decide whether to retry. Because sibling Nodes may share a name, never assume
an arbitrary same-name result is the Node created by the interrupted request.
Rename an organizational or Resource Node by stable Node ID:
uvw space node rename \
<node-id> --name <new-name> --json
Move a Node by choosing exactly one destination form. Use --root only when the intended
destination is the current Space root:
uvw space node move \
<node-id> --parent <destination-node-id> --json
uvw space node move <node-id> --root --json
Rename and move are direct desired-state Space writes. If their write response is interrupted, the
CLI reads the same stable Node ID and reports success only when current metadata matches the requested
name or parent. If it still returns workspace-result-unknown, inspect the relevant directory before
deciding whether to issue another write.
Trash is a user-authorized recursive lifecycle action. Run it only when the user explicitly asks to remove that Node subtree from its Space location:
uvw space node trash <node-id> --json
Read and retain the returned trashBatchId and nodeCount. Trash creates a new batch and is not
blindly retryable: after workspace-result-unknown, do not issue the command again because the first
request may already have moved the subtree and the batch identity was not confirmed. The current CLI
does not restore or permanently remove Trash Batches.
Worktree rule
Start every new task in a new Worktree. Do not select or reuse an active Worktree merely because
its name, Space, or Unit looks suitable. pr list is diagnostic; it is not permission to
continue someone else's or another task's draft.
Continue an existing Worktree only when all of these are true:
- The current request is rework or a correction for the same task.
- This Agent already worked on that task in a known Worktree. Resolve that same Worktree from retained task context or from an id the user supplies specifically for this rework.
- The Worktree is still
draftorready.
For rework, continue a draft Worktree directly. Reopen a ready Worktree before editing. Never
reuse a merged or discarded Worktree; start a new Worktree instead. If task-to-Worktree identity
is uncertain, start a new Worktree rather than guessing.
Connect
Point the CLI at the user's Workspace deployment before connecting, then use the two-command browser approval protocol below. Never ask the user for a password.
# Point the CLI at the user's Workspace deployment:
uvw config set workspace.origin https://workspace.example.com
# Step 1: create an approval request. This command exits immediately.
uvw auth login --json
# Step 2: relay verificationUrl and userCode to the user, then STOP.
# Do not poll, do not run --complete, and do not continue the Workspace task.
# Wait until the user explicitly says that they approved the request.
# Step 3: only after that user confirmation, exchange the approval once.
uvw auth login --complete --json
# Compatibility only, when the caller already owns a password secret:
printf '%s\n' "$WORKSPACE_PASSWORD" | uvw auth login --username <name> --password-stdin
uvw auth status --json
uvw repo list --json
repo list shows repositories you own or have joined. Open another public repository with
uvw repo view <owner>/<slug>.
Exit code 4 means sign-in is required. Run uvw auth login, or uvw auth guest when the guest path
below applies. Do not retry the failed command. No command creates a guest agent on its own.
--json prints the bare object or array (no { issue } or { worktree } wrapper); --json id,number
keeps only those top-level fields.
The first command returns status: "authorization_required", verificationUrl, userCode,
expiresAt, and nextCommand. The completion command also exits immediately: it returns
status: "authenticated" on success or status: "authorization_pending" if the browser approval
has not finished. If it is still pending, show the same URL/code to the user and wait for their
reply; do not create a polling loop. Password, GitHub, and Discord browser accounts all use this
same handoff.
Continue as a guest agent
Use the guest path when the user has no Workspace account, or asks for a new file and its link without signing in. When the work belongs in the user's own repositories, use the browser approval above.
uvw auth guest --label "<short task name>" --json
The command creates a new agent and stores its session. It returns agent.username and repo, the
agent's Personal Space repository <username>/personal. Pass repo with -R. A guest agent works
only in that Personal Space. It cannot create or join a Team Space, and it keeps at most 20 files of
at most 10 MiB each. uvw auth status --json reports subject.kind: "agent" for a guest session and
no kind for a person.
uvw auth guest refuses while a session is stored for the origin, and creates nothing. Do not run
uvw auth logout to get past the refusal unless the user asks. Logout discards the stored session,
and the CLI cannot sign in to the same agent again.
A guest session lasts as long as a Workspace session, 7 days by default. Use does not extend it.
After it ends, commands exit with code 4. Run uvw auth logout and then uvw auth guest. That
creates a new agent with an empty Personal Space, and the old agent's files can no longer be changed.
Links that the old agent shared keep working until the old agent expires, 30 days after it was last
used or one of its links was last opened.
Work from an Issue
When the user asks you to handle an Issue ("work on #12"), the Issue is the brief. Do not ask the user to restate it.
Resolve an owned or joined repository with
repo list, or a public repository withuvw repo view <owner>/<slug>, and read the Issue with its whole discussion:uvw issue view 12 -R <owner>/<slug> -c --jsonThe newest comments may change or narrow the request; read them before acting. Without a repository,
uvw search issues -a @me --jsonshows the work assigned to the user across Team Spaces.references[]lists the files the Issue points at. Useresource.idas theresourceIdandnodeIdto stage them. A reference withavailable: falsewas trashed or became unreadable; say so instead of guessing which file was meant.Follow "Start a new task" in a new Space-scoped pull request titled
#12 <Issue title>. The Worktree does not link to the Issue itself, so that name is what ties them together for reviewers.Verify and hand off as usual, then report on the Issue. Post the review URL with what you changed; write multi-line Markdown through stdin so nothing needs shell escaping:
uvw issue comment 12 -R <owner>/<slug> -F - --json <<'MD' Updated `Budget!B12` to include the East region. Review: <review-url> _Posted by an agent on the user's behalf._ MDLeave the Issue open. Closing it (
issue close) or merging the Worktree is the user's decision; do either only when they ask.
Issue writes are not idempotent. If a create or comment fails with workspace-result-unknown,
read issue view ... -c before repeating it, or the discussion may end up with a duplicate.
Labels and assignees need triage rights; when the CLI reports FORBIDDEN, tell the user rather than
working around it. Use issue create to record follow-up work you found but were not asked to do.
Start a new task
Modify an existing file
- Resolve an owned or joined repository with
repo list, or a public repository withuvw repo view <owner>/<slug>. - Find the Resource Node. Prefer
space find; usespace browsewhen tree context matters. - If multiple candidates match, compare
path,spaceId,nodeId,resourceId, and Unit type. Ask the user when the target remains ambiguous; never pick one by name alone. - Create a new pull request (Worktree), then stage the exact
resourceId. - Read the returned
idandnumber(the--worktreevalue is theid), then rununit listto confirm the staged Unit.
For a Personal Space file, use a new user-scoped Worktree:
uvw space find <document-name> --space <username>/personal --unit-type doc --json
uvw pr create -R <username>/personal -t <task-name> --json
uvw unit add \
--worktree <new-worktree-id> --resource <resource-id> --json
uvw unit list --worktree <new-worktree-id> --json
For a Team Space file, choose scope deliberately:
- Use
-R <username>/personalfor a private Agent task. - Use
-R <owner>/<slug>of the Team Space when the task itself belongs to that Team Space. Add--visibility spaceonly when Space members should see the Worktree.
After creating the Worktree, add the Resource with
unit add --worktree <new-worktree-id> --resource <resource-id>. Use the returned unitId for
all subsequent content commands; do not continue with the Node or Resource ID.
Create a new file
Create a new Worktree first, then create or import one Worktree-local Unit:
uvw pr create -R <owner>/<slug> -t <task-name> --json
uvw unit create \
--worktree <new-worktree-id> --space <owner>/<slug> \
--type sheet --name <file-name> [--parent <node-id>] [--idempotency-key <key>] --json
Use unit create for an empty Unit. Use compile-markdown --apply for a generated Modern Doc
without creating a placeholder; load the Doc Skill first. Use import --file when an office file
supplies the initial content. Do not add an unrelated Unit to an existing task Worktree.
unit create, import, compile-markdown --apply, and compile-typst --apply allocate all three
identities on the server.
They accept --idempotency-key <key>. Normally omit it and let the CLI generate one. If a final
workspace-result-unknown diagnostic returns a key, reuse that exact key only to retry the same
logical operation; use a new or omitted key for an intentional second copy.
Continue same-task rework
Use only the already-known Worktree:
uvw pr view <n|worktree-id> -R <owner>/<slug> --json
uvw unit list --worktree <worktree-id> --json
If it is ready, reopen it before editing:
uvw pr ready <n> -R <owner>/<slug> --undo --json
If it is merged or discarded, start a new Worktree and stage the current Space file again.
Edit one Unit
Before writing Facade code, load the matching versioned Skill:
- Doc:
uvw skills get doc(Modern Docs usecompile-markdown; export selected current native blocks withexport-markdownbefore partial updates) - Sheet:
uvw skills get sheet - Slide:
uvw skills get slide - Base:
uvw skills get base - Board:
uvw skills get board
For cross-Unit composition, also load the matching Topic Skill after the Host and Source Skills:
- Embed:
uvw skills get embed - Cross-Unit formula in a Sheet cell or formula-driven Shape:
uvw skills get cross-unit-formula - Chart backed by another Unit's Sheet or Base data:
uvw skills get embed(see "Referencing another Unit's data from a Chart")
Both Topic Skills persist the stable Source unitId in Host metadata and load Source data on demand;
they do not resolve identity from a display name or require staging a read-only Source into the task
Worktree.
Every content command requires the full remote address:
uvw execute \
--worktree <worktree-id> --unit <unit-id> -e '…' --json
uvw read 's1!A1:C9' \
--worktree <worktree-id> --unit <unit-id> --json
For raw Sheet cell metadata such as si or custom:
uvw inspect range A1:C9 \
--worksheet name:<sheet-name> \
--worktree <worktree-id> --unit <unit-id> --json
There is no implicit Unit and no separate save command. execute commits captured mutations as one
revision; read-only code creates no revision. inspect is always read-only.
Embedded image commit behavior
Use the public Facade with the original image source. The system automatically converts supported
BASE64 images to Workspace FileIds and stores their bytes separately, which keeps collaboration
snapshots smaller and improves loading performance; browser clients load those images automatically.
No manual image upload, format conversion, or mutation-storage handling is needed. This applies to
execute; Docs created by compile-markdown, compile-typst or import keep their images inline, so
readback returns BASE64 data URIs that already contain the bytes.
When Facade readback returns a UUID and the original asset bytes are needed, download them through the managed CLI path:
uvw asset download <output> --id <uuid> --worktree <worktree-id>
Facade API lookup
- When no relevant class or API symbol is known, use
uvw api find <query...>with API-name keywords or identifier fragments. - When a class is known, use
uvw api show <Class>to inspect its supported APIs. - When a type or exact
Class.membersymbol is known, useuvw api show <symbol>for its authoritative signature, documentation, referenced types, and examples.
find is case-insensitive. Each query is searched independently and returns its own matches;
queries are not combined as AND, and find does not interpret intent. Pass a useful symbol returned
by find directly to show instead of searching for that symbol again.
show accepts one or more exact symbols. When several relevant symbols are known, pass them in one
command. Only find accepts --unit sheet|slide|doc|base|board; use it to reduce irrelevant
Unit-specific results while retaining shared APIs. Do not pass --unit to show, and do not guess
signatures, parameter shapes, or enum values.
execute injects only the selected root: Sheet → workbook by explicit
getWorkbook(unitId), Doc → doc, Slide → presentation, Base → base, and Board → board.
Never redeclare these bindings. Sheet execution never uses the active Workbook.
Verify and hand off
After mutations:
- Verify Sheet values, types, and formulas with
read --json. Useinspectfor other Unit types or raw cell metadata. - Capture screenshots for Sheet layout, Doc pagination, and every Slide page.
- Mark the Worktree ready.
- Read it back and confirm state
ready. - Generate the review URL for the edited Unit.
- Return the review URL, pull request number, Worktree id, and Unit id to the user.
uvw pr ready <n> -R <owner>/<slug> --json
uvw pr view <n> -R <owner>/<slug> --json
uvw browse <n> -R <owner>/<slug> --unit <unit-id>
Do not merge or discard unless the user explicitly requests that consequential action. pr discard is
irreversible. There is no pr close or pr reopen; to take a ready pull request back to draft use
pr ready <n> --undo. A later
same-task correction follows the rework flow above.
Hand off as a guest agent
The user cannot open a guest agent's pull request, so a guest agent finishes the task itself. After step 4, merge the pull request, turn on Link Sharing for the file, and return the link instead of the review URL:
uvw pr merge <n> -R <username>/personal --json
uvw share <node-id> --link viewer --json
share takes the file link or the nodeId from unit create. --link viewer lets anyone who has
the link read the file without signing in. --link editor also lets signed-in people edit it.
--link off stops sharing. Without --link, the command only reads the current setting. Only the
owner of a file can read or change its Link Sharing. Give the user url. When the result has
expiresAt, tell the user that the link stops working on that date unless the agent is used or the
link is opened before then.
With a person's session, treat uvw share --link like a merge: run it only when the user asks.
Command map
Use uvw <command> --help as the syntax authority. -R <owner>/<slug> (or UVW_REPO) selects the
repository; there is no stored default repository.
outline, read, and find accept only Sheet Units. They can use --trunk instead of --worktree <id> for shared content. Use inspect for other Unit types.
outline, read, find, inspect, and screenshot accept a file link as --unit.
| Intent | Commands |
|---|---|
| Connect | config set workspace.origin, auth login, auth guest, auth status, auth logout |
| List owned/joined repositories or view a public repository | repo list, repo view <owner>/<slug>, repo create/edit/rename |
| Discover/organize files | space browse, space find, space node create/rename/move |
| Read and update Issues | issue list/view/create/edit/comment/close/reopen, label list/create/edit/delete, search issues |
| Preserve original files | blob upload, blob get, blob download, blob replace |
| Start a task | pr create, unit create, unit add |
| Inspect a known task | pr view, pr list, unit list |
| Continue same-task rework | pr ready <n> --undo |
| Map a Sheet Unit | uvw outline --unit <id> --worktree <id> [--at <ref>] [--from <ref>] [--depth <0|1|2>] [--budget <chars>] (Sheet only) |
| Read Sheet cells | uvw read <range> --unit <id> --worktree <id> [--json] (Sheet only) |
| Find Sheet cells | uvw find <terms...> --unit <id> --worktree <id> [--in values|formulas] [--from <cell>] [--max <hits>] (Sheet only) |
| Write | execute, compile-markdown, compile-svg, compile-typst, import |
| Verify | inspect, screenshot |
| Deliver output | export, print-pdf |
| Hand off | pr ready, browse <n> --unit <id> |
| User-authorized lifecycle | pr merge, pr discard (irreversible) |
| Share a file by link | share <file-link-or-node-id> [--link off|viewer|editor] (a guest agent shares its own result) |
| User-authorized cleanup | space node trash |
| Find APIs/assets/guidance | api find/show, resources, skills |