Files

T

coolguyandClaude Opus 5 eff5cbfb12 docs: make the CLI the source of truth for ferro-vm commands

명령 목록이 tools/README.md와 argparse 정의 두 곳에 손으로 동기화되고 있었다.
드리프트가 불가피하므로 목록을 --help로 단일화한다.

cli.py에 서브커맨드별 help/description, 인자 metavar, 예시 epilog를 채웠다.
put의 DOS 8.3 이름 제약처럼 명령에 직접 붙는 함정은 해당 도움말에 넣었다.
tools/README.md는 호스트 요구사항, 셋업, 자동화 구조로 줄이고 목록은 --help로
넘긴다. AGENTS.md에는 CLI가 규범이라는 포인터를 남긴다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012PQm6oAvWX4Lp3iSN5AHGT

2026-08-16 17:01:30 +09:00

1.7 KiB

Raw Blame History

Development tools

Host support

Automation currently supports Windows 10/11 only. It requires uv, QEMU with WHPX support, and ffmpeg.exe on PATH. The Python implementation uses portable APIs where possible, but other hosts are not supported yet.

Getting started

uv run ferro-vm start
uv run ferro-vm status

The command list lives in the CLI itself, not in this file:

uv run ferro-vm --help
uv run ferro-vm <command> --help

Working rules, verification gates, and DOS build traps are in AGENTS.md.

How it fits together

TCPAGENT.EXE runs inside FreeDOS and dials out to 127.0.0.1:5558; its wire protocol is documented in tcpagent/README.md. The ferro-vm daemon owns that connection and the QEMU monitor. Local commands reach the daemon over the Windows named pipe \\.\pipe\ferrolang-vm — there is no controller or observer TCP port.

The daemon writes an append-only structured log (uv run ferro-vm logs, which uses lnav when installed and otherwise falls back to PowerShell Get-Content -Wait). It records command metadata, DOS output, exit status, transfers, and agent lifecycle events as UTF-8 lines, and deliberately never logs raw binary payloads or protocol hex.

reset quits QEMU cleanly, restarts it, waits for FreeDOS to boot, submits the default boot-menu Enter, and requires a TCPAGENT PING/PONG before returning. QEMU system_reset is intentionally unsupported: repeated soft resets leave the FreeDOS NE2000 packet driver stuck during initialization.

Standalone OCR

tools/qemu_ocr.py remains available for OCRing an existing image:

uv run python tools/qemu_ocr.py --image .qemu/qemu-screen.png

1.7 KiB Raw Blame History