Skip to main content
This reference lists all 84 commands in the verified CLI release. Start with the CLI guide for a walkthrough or CLI reference for output and error handling. Run tekma COMMAND --help to check your installed version. Angle-bracket arguments are required; square-bracket arguments are optional. Replace placeholders with your own values. OAuth scopes do not override your current workspace role, folder access or privacy settings. Commands that change or send data require an explicit action; do not run them just to inspect a capture. Use --json before or after a command for structured output. Piped output is already JSON; doctor stays human-readable. Download the machine-readable catalog, or run tekma agent-context to inspect your installation.

Install and maintain

version

tekma version Report package/build version, OS and installation manager; also —version. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: Version, source revision, dirty build flag, platform, architecture, Node version and installation ownership.

install

tekma install Install a verified release into a new dedicated user-local prefix (macOS/Linux). Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: Installed version, build, SHA256, prefix, executable and PATH directory. Requires Node 22.17+ and npm.

upgrade

tekma upgrade Verify, stage and atomically activate a release in this managed installation. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: Upgraded/unchanged receipt. npm-managed executables refuse self-update with npm guidance.

uninstall

tekma uninstall Remove only this owned user-local installation, preserving credentials, recordings and skills. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: Removed prefix and retained data categories. Refuses changed launchers, foreign files and symlinks.

agent-context

tekma agent-context Emit this catalogue as JSON, so an agent can discover the CLI instead of guessing. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: { version, exitCodes, commands[] }

doctor

tekma doctor Check configuration, credentials and reachability. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: human-readable report

Authentication and skills

skills list

tekma skills list List skills bundled with this CLI; no login required. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: { skills[] }

skills show

tekma skills show <name> Read a bundled skill and its supporting references. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: { name, description, files[] }

skills path

tekma skills path Preview the skill installation directory without writing files. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: { path }

skills source

tekma skills source [name] Locate a bundled SKILL.md; defaults to tekma-recorder. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: { name, path }

skills install

tekma skills install [name] Install a bundled skill without overwriting an existing skill. Defaults to tekma-recorder and to every agent directory found in your home (~/.codex, ~/.claude). Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: { name, path, status, hint } or an array, one per agent

auth login

tekma auth login Sign in and store a token for later commands. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: { status, storedIn, refreshable, scopes[] }

auth status

tekma auth status Verify your user, authentication method, scopes and accessible workspaces online. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: { authenticated: true|false|null, credentialPresent, verification, source, endpoint, user?, authMethod?, scopes?, workspaceId?, workspaces?, workspacesTruncated? }

auth logout

tekma auth logout Revoke a stored OAuth refresh token where supported, then forget the local credential. PAT removal is local only. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: { status, localCredential, refreshTokenRevocation, accessTokenRevocation, message? }

Record and import

inspect trace

tekma inspect trace <file> Inspect local Playwright page IDs and screencast timing without uploading or authenticating. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: { traceVersions, playwrightVersions, importSupported, pages, videoStartMonotonicMs: null, alignment }

create capture

tekma create capture [source] Create an independently uploaded image/video capture from strict JSON, @file, or stdin. Requires normal media validation and OAuth upload permission. Permissions: captures:record Every input requires screenDimensions. The local FFmpeg-free path accepts WebM only and requires posterImagePath, durationMs, width, height and micEnabled together. Imported pixels and audio are not automatically redacted. Result: Normal import receipt with durable checkpoint. screenshotMediaId copies a current same-workspace screenshot and additionally requires captures:read. Video input may supply posterImagePath, durationMs, width, height and micEnabled together to bypass local FFmpeg; server media validation still applies.

import resume

tekma import resume <directory> Resume a retained image or video import checkpoint. Permissions: captures:record Result: { status, captureId, shareUrl?, checkpoint, imported, hint }

import video

tekma import video <file> Import a local video, preserving its dimensions and first available audio track while transcoding to WebM. Optional trace import adds verified, aligned diagnostics. Permissions: captures:record Only the first video stream and optional first audio stream are imported. This is not an original-byte or all-audio-track archive. The —idle-threshold-ms option requires —trace and can remove visible activity that has no matching diagnostic event. Review the result. Result: { status, captureId, captureUrl?, shareUrl?, durationMs, imported, diagnosticsAvailable, hint }

import image

tekma import image <file> Upload a PNG, JPEG, or WebP image without inventing diagnostics. Permissions: captures:record Imported pixels are not automatically redacted. Review and redact the source image before upload. Result: { status, captureId, captureUrl?, shareUrl?, imageBytes, mimeType, imported, diagnosticsAvailable, hint }

record displays

tekma record displays List explicit native capture target IDs. No frames captured; no browser diagnostics. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: { backend, targets: [{ id, width?, height?, x?, y? }], limitations }

record windows

tekma record windows List explicit native capture target IDs. No frames captured; no browser diagnostics. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: { backend, targets: [{ id, width?, height?, x?, y? }], limitations }

record desktop

tekma record desktop [command] Record a native display/window in the foreground; defaults to the primary display. Stops after duration or Ctrl-C, finalizes silent video, and uploads unless —local. No pixel redaction or browser diagnostics. Permissions: captures:record Native capture supports macOS displays, isolated windows on macOS 15 or newer, and local Linux X11 displays/windows. Wayland and Windows native capture are unsupported. Linux X11 window capture requires a visible, uncovered window; overlapping windows may appear. Audio and browser diagnostics are not recorded. Upload limits still apply when —until-stopped removes the local timer. —until-stopped is standalone-only and cannot accompany a child command. Upload requires OAuth or a recording link; a personal access token is not sufficient. Result: Recording receipt with local files, backend/target, duration, stopReason and explicit unavailable diagnostics/audio/redaction. Early source failures retain partial media locally and exit nonzero.

record run

tekma record run <command> Record a browser while a command runs, then finalize even when the command fails. Pass the command after —; child output goes to stderr. Permissions: captures:record Result: Recording receipt plus commandExitCode, commandSignal and timedOut. Nonzero child exits take precedence over finalization errors; stdout remains JSON when piped.

record start

tekma record start Start recording the browser an agent is driving by attaching over CDP. The recorder shares that browser session; review capture and privacy requirements before starting. Permissions: captures:record Result: { status, page, title, pid }

record open

tekma record open <url> Launch a Chromium on a URL and start recording it, for agents with no browser tooling of their own. Permissions: captures:record Result: { status, page, title, pid }

record stop

tekma record stop Finalize the recording and upload unless it is local-only. Return the available capture or share link when publication and workspace policy permit it. Permissions: captures:record Result: { status: uploaded | saved_locally, captureId, captureUrl, shareUrl, durationMs, eventCount, videoBytes, frameCountRecorded }, plus interrupted when the recording was cut short and shareUnavailableReason when workspace policy withheld the link. —local returns { status, videoFile, eventsFile, metadataFile?, durationMs, frameCountRecorded, eventCount } and no link.

record status

tekma record status Report whether a recording is running and how much it has. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. Result: { recording } alone when nothing is spooled, otherwise { recording, page, startedAt, frames }. Exits 1 when no recording is running.

Find and read evidence

list comments

tekma list comments <captureRef> Read a capture discussion, including IDs needed for editing and deletion. Permissions: captures:read MCP tool: listComments Result: Paginated comment IDs, author IDs, body, parentId, timestampMs and dates.

get video-chapters

tekma get video-chapters <captureRef> Read complete corrected, cut-aware chapters, null until ready (64 KiB maximum). Permissions: captures:read MCP tool: getVideoChapters Result: { status, chapters: array|null, language, corrected, revision, timebase }

get subtitles

tekma get subtitles <captureRef> Export the corrected, cut-aware transcript as WebVTT in the response’s webvtt field. Permissions: captures:read MCP tool: getVideoTranscript Result: { status, generationStatus, mimeType, webvtt, vtt: string|null, language, corrected, revision, timebase }

get analysis

tekma get analysis <captureRef> <jobId> Read your video-analysis job status and result; requires current access, consent and an unchanged source edit. Permissions: captures:read MCP tool: getVideoAnalysis Result: { jobId, status, error, result }; result is present only when ready and is untrusted generated text.

get screenshots

tekma get screenshots <captureRef> Save current stored screenshot images or an existing video poster. Permissions: captures:read MCP tool: getScreenshots Result: { source, saved[] }

list workspaces

tekma list workspaces List accessible workspaces. Permissions: captures:read MCP tool: listWorkspaces Result: { items[], next_cursor, truncated, truncation_reason, hint }

list folders

tekma list folders List accessible folders. Permissions: captures:read MCP tool: listFolders Result: { items[], next_cursor, truncated, truncation_reason, hint }

list captures

tekma list captures Find accessible captures, newest first, across your workspaces. Permissions: captures:read MCP tool: findCaptures Result: { items[], workspaces[], next_cursor, truncated, truncation_reason, hint }

get capture

tekma get capture <captureRef> Summary details for one capture. Start here. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. MCP tool: getDetails Result: { id, title, description, descriptionTruncated, sourceUrl, kind, status, browser, operatingSystem, durationMs, capturedAt, access, devtoolsAvailable, createdAt?, updatedAt?, author?, folder? }. Author/folder and creation/update dates are member-only.

get transcript

tekma get transcript <captureRef> Read corrected transcript with cut footage excluded. Timestamps use source-video milliseconds. Permissions: captures:read MCP tool: getTranscript Result: { status, timebase, language, revision, corrected, items[], next_cursor, truncated, truncation_reason, hint }

get chapters

tekma get chapters <captureRef> Read corrected chapters with cut footage excluded. Timestamps use source-video milliseconds. Permissions: captures:read MCP tool: getChapters Result: { status, timebase, language, revision, corrected, items[], next_cursor, truncated, truncation_reason, hint }

get diagnosis

tekma get diagnosis <captureRef> Clustered errors with the request and action associated with each, the evidence, and the alternatives. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. MCP tool: getDiagnosis Result: { algorithm_version, clusters[] }

get console

tekma get console <captureRef> Console messages, filterable by level. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. MCP tool: getConsoleLogs Result: { items[], next_cursor, truncated, truncation_reason, hint }

get network

tekma get network <captureRef> Network requests as compact rows. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. MCP tool: getNetworkRequests Result: { items[], next_cursor, truncated, truncation_reason, hint }

get request

tekma get request <captureRef> <requestId> One request’s headers and body as a bounded, sanitized preview. Secrets are removed and truncation is reported. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. MCP tool: getNetworkRequest Result: { requestId, method, url, status, requestHeaders, responseBody, … }

get events

tekma get events <captureRef> All recorded event types, with bounded sanitized JSON previews. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. MCP tool: getEvents Result: { items[], next_cursor, truncated, truncation_reason, hint }

get user-events

tekma get user-events <captureRef> Recorded clicks, typing and navigation in chronological order. Requires diagnostic access. Permissions: captures:read MCP tool: getUserEvents Result: { note, items: [{ at, atMs?, kind, target, selector?, pageUrl? }], next_cursor, truncated, truncation_reason, hint }; atMs is source-video milliseconds and omitted when the recording clock is unavailable.

get environment

tekma get environment <captureRef> Browser, operating system, viewport and extension version. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. MCP tool: getEnvironment Result: { browser, operatingSystem, viewport, extensionVersion, sourceUrl }

get intents

tekma get intents <captureRef> Read your cached, evidence-cited inferred objective, observed issue and impact. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. MCP tool: getIntents Result: { status: not_requested | queued | running | ready | failed | cancelled | stale, value, jobId? }. No generation on read. Claims are uncertain inferences.

get metadata-entries

tekma get metadata-entries <captureRef> Paginate stored capture-time metadata keys and values, in key order. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. MCP tool: getMetadataEntries Result: { source: capture_metadata, representation: key_value_entries, items: [{ key, value }], next_cursor, truncated, truncation_reason, hint }. Stored keys, not SDK events.

get metadata

tekma get metadata <captureRef> Capture metadata and, for workspace members, guest recording reference. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. MCP tool: getMetadata Result: { metadata, recordingReference? }

get frames

tekma get frames <captureRef> Still frames from the recording, saved as JPEG files. Defaults to one contact sheet of the whole timeline. Permissions: No additional OAuth scope listed; command-specific prerequisites still apply. MCP tool: getFrames Result: Saved frame files; prints their paths.

Analyze recordings

analyze video

tekma analyze video <captureRef> <requestKey> Request AI analysis of retained video frames; requires workspace consent and sends sampled footage to the configured provider. Permissions: captures:read, captures:write MCP tool: analyzeVideo Result: { jobId, status }; poll with get analysis. Findings are observations and hypotheses, not proven root causes.

analyze intents

tekma analyze intents <captureRef> <requestKey> Request AI intent inference from capture excerpts under workspace consent. Permissions: captures:read, captures:write MCP tool: requestIntents Result: { jobId, status }. Poll get intents; results belong to the requester.

Integrations

list integrations

tekma list integrations List workspace integration provider IDs and connection status. Permissions: captures:read MCP tool: listIntegrations Result: Paginated integration id, provider, status and accountLabel.

list integration-resources

tekma list integration-resources <captureRef> <provider> <resource> Look up valid issue destinations and metadata for GitHub, GitLab, Linear, Jira, Asana, ClickUp, Slack, Notion or Azure DevOps. Permissions: captures:write MCP tool: listIntegrationResources Result: { items: [{value,label}], nextPage, nextCursor, canChooseDestination, destination, fields?, blockedFields?, asanaFields?, workspaceId?, notionFields?, dataSourceId?, azureFields?, clickupFields?, statuses?, spaceId? }

send capture

tekma send capture <captureRef> <provider> Create an external item through an already-connected workspace integration. Permissions: captures:write MCP tool: sendCaptureToIntegration Result: { id, provider, externalId, externalUrl }

Recording requests and domains

connect recording-domain

tekma connect recording-domain <url> Get a human owner-sign-in setup link; optionally wait for actual ownership and installation verification. Permissions: captures:write MCP tool: getRecordingUrlVerifyLink Result: { domainId, origin, setupUrl, requiresOwnerSignIn, verified, humanActionRequired, installationStatus, timedOut }

verify recording-domain

tekma verify recording-domain <domainId> Check a domain’s public ownership proof as an owner; does not verify recorder installation. Permissions: captures:write MCP tool: verifyRecordingDomain Result: { domain, verified, installationStatus }

delete recording-domain

tekma delete recording-domain <domainId> Remove a domain ownership registration as an owner; captures and recording links remain. Permissions: captures:write MCP tool: deleteRecordingDomain Result: { id, deleted, changed }

create recording-domain

tekma create recording-domain Register a public HTTPS recording origin as an owner; returns public ownership instructions. Permissions: captures:write MCP tool: createRecordingDomain Result: { domain, ownershipProof, installationStatus }

get recording-domain-setup

tekma get recording-domain-setup <domainId> Get the owner sign-in page for a registered domain’s ownership setup. Permissions: captures:read MCP tool: getRecordingDomainSetup Result: { domain, setupUrl, requiresOwnerSignIn, installationStatus }

list recording-domains

tekma list recording-domains List registered recording domains and their current saved ownership and installation status as a workspace owner. Listing does not perform a new verification. Permissions: captures:read MCP tool: listRecordingDomains Result: { items[], domains[], next_cursor, truncated, truncation_reason, hint }; domains aliases the current page. tekma list recording-links List workspace recording links newest first, without revealing secrets. Permissions: captures:read MCP tool: listRecordingLinks Result: { items[], next_cursor, truncated, truncation_reason, hint } tekma get recording-link <recordingLinkId> Get recording-link metadata without revealing its secret. Permissions: captures:read MCP tool: getRecordingLink Result: Recording-link metadata and status, without credentials. tekma list recording-link-captures <recordingLinkId> List captures submitted through one recording link, newest first. Permissions: captures:read MCP tool: listRecordingLinkCaptures Result: { items[], next_cursor, truncated, truncation_reason, hint } tekma create recording-link Create a recording link as a workspace owner; returns its URL once. Permissions: captures:write MCP tool: createRecordingLink Result: { id, expiresAt, url } tekma update recording-link <workspaceId> <recordingLinkId> Update an active recording link as a workspace owner without changing its secret URL. Permissions: captures:write MCP tool: updateRecordingLink Result: Updated metadata only; no secret URL. tekma revoke recording-link <recordingLinkId> Revoke a recording link as a workspace owner; keep existing recordings. Permissions: captures:write MCP tool: revokeRecordingLink Result: { id, revoked, changed }

Collaborate and manage captures

move capture

tekma move capture <captureRef> Move a capture to a workspace folder or return it to Unfiled. Permissions: captures:write MCP tool: moveCapture Result: { id, folderId }

set status

tekma set status <captureRef> <status> Archive a capture or reopen an archived capture. Permissions: captures:write MCP tool: setCaptureStatus Result: { id, status }

attach finding

tekma attach finding <captureRef> <title> <summary> Attach a structured finding to a capture discussion. Permissions: captures:write MCP tool: attachFinding Result: { id, created }

list members

tekma list members List workspace members as an owner, including their roles. Permissions: captures:read MCP tool: listMembers Result: { items[], next_cursor, truncated, truncation_reason, hint }

invite folder-member

tekma invite folder-member <folderId> Email a selected-folder invitation as an owner; recipient must verify their email and accept in the browser. Permissions: captures:write MCP tool: inviteFolderMember Result: { id, folderId, expiresAt, url, emailStatus }

set folder-members

tekma set folder-members <folderId> Replace private folder membership as an owner, or explicitly restore workspace visibility. Permissions: captures:write MCP tool: setFolderMembers Result: { id, visibility, memberIds[] }

create folder

tekma create folder create a workspace folder. Permissions: captures:write MCP tool: createFolder Result: { id, name? }

rename folder

tekma rename folder <folderId> rename a workspace folder. Permissions: captures:write MCP tool: renameFolder Result: { id, name? }

delete folder

tekma delete folder <folderId> Delete a folder; optionally permanently delete its captures with —delete-contents. Permissions: captures:write MCP tool: deleteFolder Result: { id, name? }

add reaction

tekma add reaction <captureRef> <commentId> <emoji> Add your emoji reaction on a comment (retry-safe). Permissions: comments:write MCP tool: addCommentReaction Result: { commentId, emoji, active }

remove reaction

tekma remove reaction <captureRef> <commentId> <emoji> Remove your emoji reaction on a comment (retry-safe). Permissions: comments:write MCP tool: removeCommentReaction Result: { commentId, emoji, active }

delete comment

tekma delete comment <captureRef> <commentId> Delete your own comment, or moderate as a workspace owner. Permissions: comments:write MCP tool: deleteComment Result: { id, deleted }

update comment

tekma update comment <captureRef> <commentId> <body> Edit your own comment without changing its timestamp or attachments. Permissions: comments:write MCP tool: updateComment Result: { id, body, timestampMs }

delete capture

tekma delete capture <workspaceId> <captureId> Move to trash for 30 days; stops share access and retains media. Permissions: captures:write MCP tool: deleteCapture Result: { id, workspaceId, state, changedAt }

restore capture

tekma restore capture <workspaceId> <captureId> Restore a trashed capture and cancel cleanup. Permissions: captures:write MCP tool: restoreCapture Result: { id, workspaceId, state, changedAt }

purge capture

tekma purge capture <workspaceId> <captureId> Schedule permanent deletion of a trashed capture. Permissions: captures:write MCP tool: purgeCapture Result: { id, workspaceId, state, changedAt }

update capture

tekma update capture <captureRef> Edit a capture title or description; omitted fields stay unchanged. Permissions: captures:write MCP tool: updateCapture Result: { id, title, description }

comment

tekma comment <captureRef> <body> Post a comment onto a capture. Permissions: comments:write The —at value is source-video milliseconds from recording start, matching diagnostic atMs. It is not a wall-clock timestamp or an edited-playback offset. MCP tool: createComment Result: { id, created }