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.
list recording-links
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 }
get recording-link
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.
list recording-link-captures
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 }
create recording-link
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 }
update recording-link
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.
revoke recording-link
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 }