lemma-work/lemma-platform/lemma-user

Lemma User

You are operating inside an existing pod — use its resources (tables, files, functions, agents, workflows, connectors) to get work done for the user. You are not redesigning the pod; that's the lemma-builder skill.

This is the operator companion to lemma-builder: the runtime view of the same model. For the model itself, read lemma-builder/references/pod-model.md — this doc grounds in it and assumes it.

The model, from the operator's seat

(Grounds in pod-model.md.) A pod is one team's workspace under one permission boundary. What that means when you run commands:

• You act as a specific user. Whether a human at a terminal or an agent on

someone's behalf, every call carries your identity. A workload (function or agent) runs under delegated identity — it acts as the user who invoked it, never as a service account. So /me and row visibility always resolve to that user.

• A workload's authority is the intersection, not the union: its own grants

and what the invoking person could do themselves. A grant is a ceiling on the workload, never a promotion for the person driving it — a POD_VIEWER who invokes an agent granted datastore.record.write still cannot write through it, and someone removed from the pod can do nothing through any workload. So "the agent is granted this" is only half an answer; check the person too.

• RLS scopes what you see. On an RLS table (the per-user default) you see

and edit only your own rows — another member's row is invisible (a fetch returns 404, a list omits it). On a shared table (enable_rls: false) everyone sees the same rows. This holds for everyone, admins included; reading across all users' rows needs an explicit mode=ADMIN opt-in (admin-gated, not the default flow). The read-only query API enforces RLS the same way.

• `/me` is your private tree. /me/... resolves to your own file subtree

(owner-only). Every other path is pod-shared — top-level folders like /knowledge, /contracts. There is no `/pod` prefix: a path is shared unless it's under /me. Folder grants cascade to everything beneath them.

• Missing access has three shapes, and the refusal code says which. A human

without the pod role gets INSUFFICIENT_PERMISSION. A workload missing a grant gets MISSING_WORKLOAD_RESOURCE_GRANT, naming the resource a builder must grant. A workload that holds the grant but is acting for someone who lacks the permission gets DELEGATION_EXCEEDS_INVOKER — granting the workload more is the one fix that cannot work; give the person the permission, or run it as someone who already has it.

Put user-facing deliverables in /me (or the appropriate shared folder) — never leave the only copy in a local temp path.

Orient first

lemma pods list            # marks the currently active pod
lemma pods describe        # inventory: tables, agents, functions, workflows, schedules,
                           # apps and surfaces + a file tree
                           # tree shows 2 folder levels; --depth N / --full for more

Workspace sessions inject LEMMA_TOKEN, LEMMA_BASE_URL, LEMMA_ORG_ID, LEMMA_POD_ID (and LEMMA_WORKSPACE_URL) — use them; never invent bootstrap config. (Outside an injected workspace — e.g. running the CLI on a laptop — project-root .lemma.<server>.env files supply the same LEMMA_* values per server for that folder; injected/real env always takes precedence.) Default output is a compact, complete table/detail view (schemas included) — prefer it; it costs far fewer tokens than JSON. Use --output json (or --json) only to pipe/save, and --full to expand folded fields. Errors, warnings and progress lines go to stderr, so stdout carries the result and nothing else: lemma --json … | jq stays parseable even when the command fails, and you never need to redirect to keep the JSON clean. Pass payloads with --data '<json>' (-d) or --file path.json (-f); target another pod with --pod <id-or-slug>. --yes skips a command's confirmation prompt — use it only where you already know exactly what the command will touch, and never on `conversations approve`, where it silently authorises every gated call queued on the conversation (see "conversations approve" below). CLI groups are plural (lemma files, lemma tables, lemma records, …), and most have a singular alias (lemma file, lemma table). Not all: query, datastore, runtime, servers, telemetry, auth, and config exist only as written. There is no lemma tools group — first-party tools are the in-process agent tools described below, not a CLI surface.

For multi-step scripting prefer the Python SDK over chained CLI calls:

from lemma_sdk import Pod
pod = Pod.from_env()       # auth + pod from the environment

Files — the pod is a searchable knowledge base

This is the area you'll lean on most. Uploaded documents are auto-indexed — the pod *is* the RAG system. PDF/DOC/DOCX/ODT/RTF/Markdown/text/HTML/EPUB are extracted, chunked, embedded, and converted to page-marked markdown on upload. That allow-list is the whole of it: spreadsheets and tabular data (CSV, TSV, JSON, YAML, XLSX, ODS), presentations (PPTX, ODP), images (no OCR), email (.eml/.msg), audio, video and archives are stored but never indexed — they won't appear in search. So: search to find, cat to read, child + view-image to see.

Because the pod auto-produces a document's markdown, page images, and figures, read those first (the commands below) — never re-parse a pod file. Reach for the liteparse-documents skill (lit) only for a document from outside the pod (e.g. a PDF an agent fetched from the web) or as a fallback when a pod file's derived artifact is missing or insufficient (scanned/OCR, bounding boxes).

Search — find the relevant passages

lemma files search "refund policy" --scope /knowledge                 # HYBRID, folder + all subfolders
lemma files search "termination clause" --scope /contracts --method VECTOR   # semantic only
lemma files search "invoice 4471" --scope /inbox --method TEXT --direct      # keyword, immediate children only

Results are ranked passages with page numbers, so you can jump straight to cat … --pages N. --scope + the default SUBTREE (folder and everything beneath) is your retrieval lever — scope a search to one knowledge folder to keep it tight. --method is HYBRID (default), VECTOR (semantic), or TEXT (keyword); --direct limits to a folder's immediate children — it only takes effect alongside --scope, and is ignored without one. Reach for search before reading whole files or guessing.

Read — cat is page- and mode-aware

lemma files cat /knowledge/handbook.pdf                 # auto: raw text for .md/.txt, converted markdown for PDF/DOCX/…
lemma files cat /knowledge/handbook.pdf --pages 3-7     # 1-based page slice over the converted markdown (great for long books)
lemma files cat /me/notes/log.md --lines 10-50          # 1-based line slice over raw text
lemma files cat /knowledge/handbook.pdf --mode markdown # force converted markdown (errors if not a document)
lemma files cat /scratch/data.csv --mode text           # raw bytes (binary → flagged, not dumped)

--mode is auto (default) / text / markdown. Output is capped at ~50,000 chars by default (matching the in-process agent tool); widen with --max-chars 0 (unlimited), --max-lines N, --max-tokens N, or --full, or narrow with --pages / --lines. The payload reports page_count, the returned range, and a truncated flag so you know when to page — page-range slicing is how you read a long document without blowing the budget.

lemma files download /knowledge/handbook.pdf ./handbook.md --markdown   # save converted markdown
lemma files download /knowledge/handbook.pdf ./handbook.pdf             # exact original bytes

See — child page images + view-image

A processed document exposes hidden child artifacts at <file-path>/<artifact>:

lemma files children /knowledge/handbook.pdf                          # list them
lemma files child /knowledge/handbook.pdf/document.md --pages 3-7     # page-marked markdown range
lemma files child /knowledge/handbook.pdf/pages/page_0003.jpg ./p3.jpg  # fetch a rendered page image

• …/document.md — page-marked converted markdown (<!-- PAGE n -->)
• …/pages/page_0001.jpg … — rendered page images (1-based)
• …/image_0.png … — extracted figures (at the container root, not under images/)

Use view-image to actually *see* a pod file. Those rendered page JPEGs (and any uploaded image) are exactly what the view-image capability reads — fetch one with files child (or a URL with files url) and view it to see a chart, a signature, a scanned form, a layout. So: "what does page 3 look like?" → files child …/pages/page_0003.jpg → view-image; "what does it say?" → files cat … --pages 3.

As an in-process tool, view_image takes exactly one of pod_file_path (the datastore, no download needed) or workspace_file_path (the sandbox) — it never infers the store from the path, and both or neither is an error. It handles images only; hand it a PDF and it points you at pod_view_document_pages, which renders that document's pages directly and skips the files child round trip. It rides on any vision-capable model regardless of configured toolsets, so you probably have it.

Write & transfer

lemma files mkdir /knowledge                                  # optional: upload and write create missing folders
lemma files upload ./report.md /me/reports/report.md          # documents auto-index
lemma files upload ./data.csv /scratch/data.csv --no-search   # skip indexing
lemma files write /me/notes/draft.md "first line"             # create/overwrite (or pipe via stdin)
lemma files append /me/notes/draft.md "next line"             # append (read-modify-write, last writer wins)
lemma files ls /knowledge ; lemma files tree /
lemma files stat /knowledge/handbook.pdf                      # metadata incl. indexing status
lemma files mv /me/notes/draft.md /me/notes/final.md
lemma files rm /scratch/data.csv

Indexing lags briefly after upload — stat shows status (COMPLETED = searchable, NOT_REQUIRED = stored but not an indexed document, PENDING/PROCESSING = still working, including a failed attempt waiting to be retried, FAILED_PERMANENT = out of retries or unprocessable, with the reason in last_processing_error; nothing re-drives it on its own. New bytes, or lemma files retry <path> once the cause is fixed, re-opens it; uploading the same bytes again does not).

Link to a file — pick by who opens it

lemma files url /reports/summary.pdf                           # app_url (in-app, signed-in member) + short-lived download url
lemma files share /reports/summary.pdf --ttl 3h --max-hits 50  # public, no-login, expiring + hit-capped
lemma files shares                                            # your live links (--all adds expired/revoked)
lemma files unshare CwbaUB9gWY6l                              # kill one now

url returns an app_url deep-link for pod members (must be logged in) plus a short-lived raw download url. share mints a public link anyone can open without logging in. The two are not interchangeable: signed_url is the one to send outside the pod, app_url the one to point a member at in the app.