cli-for-android: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

make build       # compile → dist/acli (with version/commit ldflags)
make test        # go test ./... -v -count=1
make lint        # go vet ./...
make install     # go install to $GOPATH/bin
make release     # cross-compile for darwin/linux/windows (5 binaries in dist/)
make clean       # rm -rf dist/

# Run a single test package
go test ./pkg/aclerr/... -v -run TestClassify

# Run a single test function
go test ./pkg/runner/... -v -run TestRunCapture_Timeout

# Build and run locally
go build -o dist/acli ./cmd/acli && ./dist/acli doctor

Architecture

The binary is cmd/acli/main.go → calls internal/cmd (Cobra tree) → delegates to service layers.

Layer map

Layer	Path	Role
CLI commands	internal/cmd/*.go	One file per subcommand group; registers with RootCmd in root.go
Domain services	internal/{sdk,avd,device,build,flash,instrument}/service.go	Business logic; calls runner and android.SDKLocator
Shared packages	pkg/	No internal imports; safe to use anywhere

Key packages

pkg/runner — all subprocess execution goes here. Run() returns (*Result, error). Use RunWith() when you only care about the error (passthrough/fire-and-forget), RunCapture() for captured output, RunWithStdin() when stdin piping is needed. Context timeout check happens before ExitError check (critical ordering — killed processes also return ExitError(-1)).

pkg/aclerr — structured errors. Every user-facing error is an *AcliError{Code, Message, Detail, FixCmds, DocsURL}. Exit codes: device errors→3, SDK/env→4, build→5, emulator timeout→6, general→1. catalog.go has regex patterns that classify raw tool stderr into structured errors via aclerr.Classify(tool, stderr).

pkg/output — call output.Init(json, verbose, noColor) once (done in PersistentPreRunE). Then use package-level Success(), Info(), Warn(), Error(), Table(), CheckList(). All functions branch internally on Default.JSON — never check the flag yourself in command code. Errors go to stderr; data goes to stdout.