wcheats CLI

The wcheats CLI is a command-line companion for WorkCheats. It helps you authenticate, browse personal library and session metadata from a terminal, and send untrusted output to the Output Inbox or session placeholders — it does not execute scripts, run commands on targets, spawn shells, or perform operational actions on your behalf.

WorkCheats displays content; you run tools separately in authorised environments. The CLI talks to WorkCheats API routes (/api/cli/v1/*) — not directly to Supabase.

The CLI is Linux-first. Browse commands are read-only; output send and link store untrusted text through opt-in write scopes and server-side entitlement checks.

Terminal Companion (in-app)

Open Terminal Companion at /home/cli in your personal workspace for CLI capabilities, beta setup guidance, and the Output Inbox list (outputs from wcheats output send).

Device-code approval during login uses /home/cli/device. Do not approve device login codes you did not request.

CLI overview

Use the CLI when you want quick terminal access to:

• Confirm you are signed in
• Search your library from the shell
• Display a stored command's content
• List workflows and view workflow summaries
• List and inspect assessment sessions
• Set local session context for faster placeholder linking
• Send terminal output to the Output Inbox
• Link terminal output to session placeholders on linked reports

Plans and access

Pro and Enterprise session/output features require API access and Reports account entitlements, plus the token scopes below. Route handlers recheck entitlements on every request. Removing Reports access revokes session/output capability on the next API call without reissuing the token.

Until Stripe subscription provisioning is active in your environment, accounts may need explicit operator grants for API access and Reports.

Beta setup — Linux x86_64 release

Linux x86_64 only. macOS and Windows are not supported for official binaries. WorkCheats does not host CLI binaries on Vercel or app routes — download from the public release repository only. There is no auto-update; replace the binary manually when a new release is published.

Release: v0.1.0 on workcheats/wcheats-releases

Download

• Tarball: wcheats-0.1.0-linux-x86_64.tar.gz
• Checksums: SHA256SUMS

The in-app Terminal Companion page at /home/cli links to the same tarball.

Verify, install, and authenticate

sha256sum -c SHA256SUMS
tar -xzf wcheats-0.1.0-linux-x86_64.tar.gz
chmod +x wcheats
sudo mv wcheats /usr/local/bin

Authenticate after install (create a token in Settings → CLI Tokens, or use device-code login):

wcheats version
printf '%s' 'wc_your-token-from-settings' | wcheats auth token --stdin

Or: wcheats auth login

Security: wcheats never executes commands — it displays and stores untrusted text only. Passing tokens as command arguments can enter shell history; prefer wcheats auth token --stdin.

Authentication flow

WorkCheats supports two onboarding paths:

Settings → CLI Tokens (frequent use and write scopes)

1. Open Personal Settings → CLI Tokens at /home/settings#cli-tokens.
2. Create a token — label, expiry (7 / 30 / 90 days), and scopes. Read scopes default on; write scopes are opt-in.
3. Copy the token when shown once — you will not see the full value again.
4. Authenticate the CLI (recommended):

export WCHEATS_API_BASE_URL=https://app.example.com
printf '%s' 'wc_your-token-from-settings' | wcheats auth token --stdin

The CLI reads stdin, verifies the token via WorkCheats API (GET /api/cli/v1/me), stores credentials locally, and does not print the token back.

Less safe (shell history): wcheats auth token <token> — same verification, but the CLI warns on stderr that argument tokens may remain in shell history. Prefer --stdin.

Do not share tokens or paste them into chat, tickets, or logs.

Device-code login (casual onboarding)

1. Run wcheats auth login — the CLI prints a verification URL and user code.
2. Sign in to WorkCheats in your browser if needed.
3. Open the approval page (typically /home/cli/device) and approve the code.
4. Return to the terminal — the CLI stores credentials locally after approval.

Approve codes only when you initiated login in your terminal.

Eligible Pro/Enterprise approval receives the permitted Pro scope set, including read:sessions, write:output_send, and write:session_outputs. Starter approval receives read:library only. Route handlers still recheck current entitlements on every request.

After login

5. Use wcheats auth status to confirm the token prefix and scopes.
6. Use wcheats auth logout to clear local credentials and stored session context.

Successful auth token or device-code approval also clears stored session context before saving new credentials.

wcheats unset session clears session context only — it does not log you out or revoke your server-side token. Revoke tokens in Settings → CLI Tokens when needed.

Current commands

The following commands are available today:

Authentication

• wcheats auth login — device-code login; store CLI credentials locally
• wcheats auth token --stdin — save a Settings-created token from stdin (recommended; not echoed or printed back)
• wcheats auth token <token> — save a Settings-created token from an argument (stderr warns about shell history)
• wcheats auth status — show whether you are authenticated (token prefix only)
• wcheats auth logout — clear local CLI credentials

Create tokens in Personal Settings → CLI Tokens (/home/settings#cli-tokens) before using auth token. Device-code login remains available for quick setup.

Search and lookup

• wcheats search <query> — search personal library commands by keyword
• wcheats show <uuid-or-row> — print the stored command body only (default; pipe-friendly)
• wcheats show <uuid-or-row> --detail — print API metadata (title, id, risk, taxonomy, tags, description, purpose, command)
• wcheats command show <uuid-or-row> — compatible alias; --plain is a legacy alias for body-only output

Search query examples

wcheats search nmap
wcheats search "nmap firewall bypass"
wcheats search nmap firewall bypass
wcheats search nmap + firewall + bypass

The CLI normalises arguments after search into one query string sent to the existing search API:

• Multiple unquoted terms are joined with spaces (nmap firewall bypass).
• Quoted phrases pass through as a single term ("nmap firewall bypass").
• + is treated as a separator, not Boolean AND (nmap + firewall + bypass → nmap firewall bypass). This does not change server-side ranking or implement true AND/OR search.

On an interactive terminal, search prints a compact bordered table: row number, full title, and full UUID (max 104 visible columns; long titles wrap). Empty results: No commands found. Piped output and TERM=dumb use plain borderless rows — no Query:, Found, risk, taxonomy, tags, or previews.

After a successful search, you can use a 1-based row number with show or copy instead of copying the UUID:

wcheats search "S4U"
wcheats show 1
wcheats show 1 --detail
wcheats copy 1
wcheats copy aabbccdd-e11b-41d4-a716-446655440000
wcheats copy 1 --resolve
wcheats copy 1 --resolve --include-sensitive
wcheats command copy 1
wcheats command copy 1 --resolve

Row numbers refer to the most recent successful search only. The CLI stores ordered command UUIDs locally — not queries, titles, bodies, metadata, variables, or tokens. The resolved UUID is still fetched through the normal API with server-side authorization. A successful zero-result search clears the previous list; failed searches preserve it; login, token replacement, and logout clear it. UUID input remains script-friendly. Invalid or missing row state fails locally without an API call.

Command show, --detail, and --plain

Default wcheats show <uuid-or-row> prints the stored command body only, plus one trailing newline.

--detail prints fields returned by the API in a bordered FIELD / VALUE table on interactive TTYs, or plain labelled text when piped or TERM=dumb.

wcheats command show <uuid-or-row> is compatible syntax. --plain remains accepted as a legacy alias for the body-only default.

• WorkCheats does not execute commands — review the body before running anything manually in your shell.
• show always leaves placeholders unresolved ({RHOST}, $TARGET, and similar tokens stay literal on stdout).
• wcheats copy and wcheats command copy fetch the sanitised body and copy it to the environment clipboard when a supported helper is available — placeholders unchanged by default, no trailing newline, no execution.
• Add --resolve to resolve non-sensitive personal global variables on the server while preserving sensitive placeholders (Starter, Pro, Enterprise; existing read:library scope).
• Add --resolve --include-sensitive to include sensitive values as well — requires --resolve; explicit on every invocation; no persistent default.
• Use wcheats show <uuid-or-row> to print the body to stdout when clipboard helpers are unavailable, or plain copy when you do not need substitution.
• Local session context (wcheats set) does not affect command output.
• Session variables and workflow-run overrides are not resolved in the CLI.
• Numbered references across multiple saved searches are not implemented.

Copy to clipboard

wcheats copy <uuid-or-row> [--resolve] [--include-sensitive] requires the same read:library scope as show. Copy is not Pro-only. Global-variable resolution requires Starter, Pro, or Enterprise.

Default copy uses the command-show API and preserves placeholders unchanged.

--resolve calls the server resolve endpoint for personal global variables only. Non-sensitive variables are substituted; sensitive placeholders remain unchanged in the copied command. The CLI never substitutes variables locally, never fetches a full variables catalogue, and never prints resolved content to stdout or stderr. Resolved content goes to the clipboard only and is not stored in last-search state or credentials.

--resolve --include-sensitive resolves sensitive and non-sensitive values and uses the normal clipboard success message after copying.

Partial-resolution success message (when sensitive placeholders remain): Copied with sensitive placeholders unchanged. Re-run with --resolve --include-sensitive to include their values. Placeholders: PASSWORD. Multiple names are comma-separated; the server may append (+N more) when the name list is capped. Placeholder names only — never values.

Resolution rules: single-brace {VAR} placeholders; one-pass substitution; repeated placeholders share one value; values are not recursively expanded; sensitive classification uses the stored flag or sensitive-name heuristic; missing or empty referenced variables fail the whole operation with nothing copied; maximum 32 KiB UTF-8 after sanitisation. Report {{field}} syntax is not CLI command-variable syntax. Session variables and workflow-run overrides are not resolved.

Failure messages (examples): --include-sensitive requires --resolve. · Variable resolution is not available for this account. Use plain copy instead. · Cannot resolve the command because required variables are missing or empty. · The resolved command is too large to copy. · Unable to resolve the command right now. · Sensitive variables require --include-sensitive. (legacy or older-server response). Error output may list placeholder names only — never values. Do not include variable values in bug reports or logs.

Backend order (optional Linux helpers):

1. wl-copy when WAYLAND_DISPLAY is set (/usr/bin/ or /bin/)
2. xclip, then xsel when DISPLAY is set
3. Inside tmux, when desktop helpers fail: tmux load-buffer -w when set-clipboard is on or external (temporary buffer deleted immediately); actionable error when off
4. Outside tmux only: OSC 52 as an unacknowledged fallback

Environment boundary: helpers affect the clipboard where the CLI runs (for example, a VM guest). Guest-to-host bridging depends on your hypervisor or desktop — not WorkCheats. Use the WorkCheats browser app when you need the host browser clipboard.

Messages: Copied to clipboard. (native helper); Clipboard copy requested through tmux.; Clipboard copy requested via OSC 52. Paste may not work in every terminal. — these are requests, not guarantees.

Terminal output

• Restrained ANSI colour on compatible interactive TTYs; set NO_COLOR=1 to disable colour while keeping Unicode table borders.
• Piped stdout and TERM=dumb use plain borderless text.
• A compact CLI banner appears only for no arguments, help (help, --help, -h), and auth login — not for search, show, or other commands.

Workflows (read-only summary)

• wcheats workflow list — list personal workflows
• wcheats workflow show <uuid> — show workflow summary metadata (no step bodies or variable resolution)

Sessions (read-only)

• wcheats sessions list — list personal assessment sessions
• wcheats sessions search <query> — search sessions by name, workflow, or linked report title
• wcheats sessions show <uuid> — show session summary; add --show-placeholders to list report placeholder keys and labels (never values)

Active sessions with a linked primary report may accept new linked output. Completed, cancelled, archived, or read-only sessions reject new links; previously linked outputs remain visible in read-only session views.

Session context (local)

• wcheats set <session_uuid> — validate a session via the API and store local session context for link
• wcheats unset session — clear stored session context only (does not log out)

set stores minimal metadata locally (normalised API base URL, session id, display names/titles, timestamps). Legacy or mismatched contexts are rejected. It does not grant permissions, change token scopes, store outputs, report bodies, tokens, passwords, or session variable values. The server still validates your token, account, session access, linkWritable, and placeholder key on every link request.

Output

• wcheats output send — send stdin or --file output to the Output Inbox only (requires write:output_send and Reports access)
• wcheats link --placeholder <key> — link stdin or --file output using stored session context from a prior wcheats set (requires write:session_outputs and Reports access)
• wcheats link <session_uuid> --placeholder <key> — link with an explicit session UUID (overrides stored context)

Output body is accepted only through stdin or --file — never as a command-line argument.

Canonical link flow:

terminal output
→ POST /api/cli/v1/outputs
→ authorised session
→ valid session placeholder
→ report already linked to that session
→ linked-output record visible in the session panel and Output Inbox detail

The server resolves the session's active primary linked report. The CLI never accepts an arbitrary report ID. Linking does not automatically replace or mutate report Markdown.

Examples:

wcheats set aabbccdd-e11b-41d4-a716-446655440000
nmap -sV 10.10.10.10 | wcheats output send --title "Scratch capture"
wcheats link --placeholder nmap_initial_scan --file nmap.txt
wcheats link aabbccdd-e11b-41d4-a716-446655440000 --placeholder nmap_initial_scan --file nmap.txt
wcheats unset session

Output safety

All terminal output is untrusted text:

• Maximum total payload: 256 KiB UTF-8 — no arbitrary per-line limit.
• Null bytes are rejected; terminal control sequences and disallowed C0/DEL controls are removed before submission and again before storage.
• Tab, LF, CR, Unicode, and literal HTML-like or Markdown-like text remain ordinary stored text.
• The CLI never executes submitted output.
• Success responses are metadata-only; output content must not enter logs, analytics, credentials, or session context.
• Output Inbox detail renders body as plain React text.

Browse commands (search, show, command show, copy, workflow list/show, sessions) read and display content only. Output commands store untrusted text via the API — WorkCheats does not execute that content.

There is no --report flag, no direct report ID target, and no automatic report Markdown mutation. output send is inbox-only. Use link to associate output with a session placeholder on the session's linked report.

Security model

• The CLI uses the same account and workspace boundaries as the web app.
• Stored CLI credentials are local to your machine — protect your workstation like any other security tool.
• wcheats never executes command bodies, workflow steps, or imported scripts.
• wcheats never spawns shells for command execution.
• Clipboard copy (copy, command copy) uses a narrow allowlisted adapter only — not general automation.
• copy --resolve resolves non-sensitive personal global variables on the server, preserves sensitive placeholders unchanged, and copies the result via the clipboard adapter only — never on show, never locally, never for session variables.
• copy --resolve --include-sensitive resolves sensitive and non-sensitive values; uses the normal clipboard success message.
• Resolved content and variable metadata are not stored in credentials or last-search state.
• Plain copy without --resolve remains available when you do not need substitution.
• The CLI calls WorkCheats HTTP API routes only — no direct Supabase access; no service role.
• Treat displayed content as untrusted operational text, not as instructions WorkCheats has validated for your engagement.
• Do not approve device login codes you did not request.

See Security & Responsible Use for authorised use and untrusted content rules.

No script execution

WorkCheats — web app and CLI — does not execute scripts or commands. The CLI shows content; your shell and tools run separately under your control.

If documentation or marketing elsewhere implies automatic execution, that is incorrect for the current product.

Output Inbox

The Output Inbox on /home/cli lists outputs sent with wcheats output send. Open an item at /home/cli/outputs/<output-id> to review untrusted plain text. wcheats link associates output with a session placeholder when your token includes write:session_outputs and your account has Reports access. Linked outputs also appear in the session runner panel.

Terminal outputs are stored as untrusted text artifacts for manual review. There is no --report, no direct report ID target, and no automatic execution or report Markdown mutation from the CLI.

Roadmap

The following CLI capabilities are not available yet:

• Masked variables list in CLI — display variable values with masking rules from the terminal (separate from copy --resolve)
• Attach inbox outputs to sessions from the UI — promote inbox items without re-sending from the terminal
• Session mutation (create, archive, run control) from the terminal — set stores local context only; it is not session control
• Auto-update for Linux binaries — replace manually when a new release is published

Roadmap items may change before release. Do not build operational processes that depend on them today.

See Workflows, Variables, and Sessions for related web app features.