AGENT SKILL

control-cli

Build or adapt a local harness to drive, inspect, and profile an interactive CLI or TUI without external services. Use for CLI UX checks, startup regressions, memory leaks, hangs, prompt flows, or terminal demos.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 5
Forks
0

01 前言 Front Matter

name
control-cli
description
Build or adapt a local harness to drive, inspect, and profile an interactive CLI or TUI without external services. Use for CLI UX checks, startup regressions, memory leaks, hangs, prompt flows, or terminal demos.

03 SKILL.md 正文

Control CLI

Use a repeatable local harness to exercise an interactive CLI instead of poking at it manually. First reuse the repo's own test/demo harness if it exists; otherwise assemble a temporary harness from standard local tools.

What It Is Used For

  • Reproducing CLI/TUI bugs with deterministic input.
  • Verifying keyboard flows, prompts, interrupts, resize behavior, and terminal layout.
  • Capturing before/after transcripts for bug fixes.
  • Profiling startup time, slow operations, hangs, or memory growth.
  • Recording a short terminal demo when output is easier to show than explain.

Harness Loop

  1. Identify the command under test and the smallest reproducible workspace.
  2. Discover existing local harnesses: package scripts, e2e tests, demo recorders, expect scripts, or PTY helpers.
  3. If no harness exists, launch the CLI in an isolated terminal session with deterministic env vars.
  4. Capture the current screen before interacting.
  5. Send one action at a time: text, Enter, arrows, Escape, Ctrl-C, resize.
  6. Wait for a concrete screen pattern or prompt before the next action.
  7. Save the transcript and any profile artifacts.
  8. Kill the session cleanly.

Harness Options

  • Repo-native harness: prefer checked-in scripts because they know the app's startup, env, and prompts.
  • tmux: managed sessions, capture-pane, send-keys, attach/detach.
  • PTY probe: use a short Python, Node, or Expect script when tmux is unavailable.
  • Runtime inspector: use Node or Bun inspector for CPU profiles, heap snapshots, and live evaluation.
  • Terminal recorder: use repo-local demo tools or asciinema-compatible tools when the user asks for a demo.

Minimal tmux Harness

SESSION="cli-harness-$(date +%s)"
tmux new-session -d -s "$SESSION" -- <command-under-test>
tmux capture-pane -pt "$SESSION"
tmux send-keys -t "$SESSION" "help" Enter
tmux capture-pane -pt "$SESSION"
tmux kill-session -t "$SESSION"

For Node CLIs:

NODE_OPTIONS="--inspect=127.0.0.1:0" tmux new-session -d -s "$SESSION" -- <node-cli-command>

Read the terminal output to find the inspector URL, then use Chrome DevTools-compatible tooling if profiling is needed.

Minimal PTY Harness

Use a PTY script when you need deterministic waits in a repo that does not have tmux or a demo harness. Keep it temporary unless the user asks to add a reusable test.

import os
import pty
import select
import subprocess
import time

master_fd, slave_fd = pty.openpty()
proc = subprocess.Popen(
    ["<command>", "<arg>"],
    stdin=slave_fd,
    stdout=slave_fd,
    stderr=slave_fd,
    close_fds=True,
)
os.close(slave_fd)

deadline = time.time() + 30
buffer = b""
while time.time() < deadline:
    ready, _, _ = select.select([master_fd], [], [], 0.25)
    if not ready:
        continue
    chunk = os.read(master_fd, 4096)
    buffer += chunk
    if b"<ready text>" in buffer:
        os.write(master_fd, b"help\n")
        break

print(buffer.decode(errors="replace"))
proc.terminate()
os.close(master_fd)

If the CLI needs richer terminal control, use pty.fork() or an existing PTY library.

Profiling Recipes

  • Startup regression: capture baseline and treatment startup timings under the same machine, env, and command.
  • Slow operation: start a CPU profile, perform the operation, stop the profile, and compare top self-time functions.
  • Memory leak: force GC if available, take a heap snapshot, perform the operation repeatedly, force GC again, and take another snapshot.
  • Hang: capture the screen, active handles/resources, and a stack/CPU sample before interrupting.

Guardrails

  • Prefer deterministic waits over sleeps. If you must sleep, explain why.
  • Do not send credentials or destructive commands into a controlled session.
  • Keep the harness in /tmp unless the repo already has a testing/demo harness.
  • Do not hard-code paths from another repository. Adapt commands to the current repo's scripts and runtime.
  • Clean up tmux sessions, temp dirs, inspector processes, and demo artifacts unless the user asks to keep them.

04 同仓库更多 Skills

just-joshn
just-joshn/pi-customizations

plant

暂无简介

★ 5
just-joshn
just-joshn/pi-customizations

vitest-best-practices

Use when writing or reviewing Vitest tests, fixing flaky or slow tests, debugging failures, structuring suites, writing assertions (toBe vs toEqual vs toStrictEqual, asymmetric matchers, expect.soft, expect.poll, vi.waitFor), testing async code, setup/teardown hooks, test context and fixtures (test.extend, aroundEach), mocking (vi.fn, vi.spyOn, vi.mock, vi.hoisted, vi.when, classes), fake timers and dates, globals and env stubs, network mocking with MSW, file system mocking, snapshots, type testing (expectTypeOf), DOM environments (jsdom, happy-dom), Browser Mode, component testing (React, Vue, Svelte), benchmarking, database/integration tests, test tags and filtering, configuration and projects (monorepos), parallelism and performance, coverage, reporters, CI sharding, or migrating from Jest or Vitest 4. Targets Vitest 5.x.

★ 5
just-joshn
just-joshn/pi-customizations

plant-run

A planted skill whose blocks compile; one test fails, one is compile-only, and one never runs.

★ 5
just-joshn
just-joshn/pi-customizations

nope

A planted skill whose every file holds a mistake the gate must report, one class of mistake per block.

★ 5
just-joshn
just-joshn/pi-customizations

compose-robolectric-best-practices

Use when writing or reviewing Jetpack Compose UI tests that run on the JVM with Robolectric, fixing flaky or slow Compose tests, debugging test failures, structuring suites, choosing finders and semantics matchers (onNodeWithText, onNodeWithTag, hasX, useUnmergedTree), assertions, actions and gestures (performClick, performTextInput, performTouchInput, performScrollTo), synchronization (waitForIdle, waitUntil, mainClock, the v2 StandardTestDispatcher test APIs), JUnit rules and fixtures, screen robots, fakes and test data, ViewModel and StateFlow screens, navigation (Navigation Compose, Navigation 3), lists and scrolling, text fields and forms, dialogs and popups, animations and the test clock, configuration changes (qualifiers, dark mode, locale, RTL, font scale, state restoration), View interop, activities, intents, permissions and back press, screenshot tests with Roborazzi, accessibility checks, Robolectric configuration (@Config, sdk, qualifiers, looper and graphics modes), CI, performance, coverage, or migrating from the v1 Compose test APIs. Targets Compose BOM 2026.09 (ui-test 1.12) and Robolectric 4.17.

★ 5
just-joshn
just-joshn/pi-customizations

create-skill

Create Cursor Agent Skills. Use when authoring a new skill or asking about SKILL.md structure.

★ 5