Skip to content

README.md

Latest commit

 

History

History
151 lines (114 loc) · 5.53 KB

README.md

File metadata and controls

151 lines (114 loc) · 5.53 KB
Raw

af CLI (Rust)

af is the deterministic CLI executor for the Autofish Service.

Install from npm

npm i -g @memohjs/af

Build

cd cli
cargo build --release

Run

SESSION="cli-demo"
af config list
af config set remote.url "http://<IP>:<PORT>"
af config set remote.token "<token>"
af config set memory.db "$HOME/.config/af/af.db"
af config set output.default "text"
af config set artifacts.dir "$HOME/.config/af/artifacts"
af config list
af app install --device <ADB_SERIAL>
af app uninstall --device <ADB_SERIAL> --dry-run
af connect usb --device <ADB_SERIAL>
af health
af --session "$SESSION" observe screenshot
af --session "$SESSION" observe screen --full
af --session "$SESSION" observe page --field screen --field refs --max-rows 80
af --session "$SESSION" act tap --by ref --value @n1
af --session "$SESSION" verify text-contains --text "Settings"
af memory search --app com.android.settings
af memory experience --app com.android.settings --activity com.android.settings/.Settings

Command groups

  • health
  • act:
    • tap (preferred: --by ref --value @nK; coordinates: --xy; semantic: --by --value [--exact-match])
    • swipe, back, home, text, launch, stop, key
  • observe:
    • page (--field screen|refs; base context is always returned), screen, refs, overlay, screenshot, top
  • verify:
    • text-contains, top-activity, node-exists
  • memory:
    • save, search, delete, experience, context, log, stats
  • recover:
    • back, home, relaunch
  • config:
    • list, get, set, unset
  • app:
    • install installs the official Autofish App over adb. Defaults to the App release matching the current CLI version.
    • uninstall removes the official Autofish App over adb.
  • connect:
    • usb reads the App connection hint, creates adb forwarding, verifies /health, and writes local connection metadata.
  • completion:
    • generates shell completion scripts for bash, zsh, fish, powershell, or elvish.

See docs/CLI_MEMORY.md for memory design details.

Shell Completion

af completion <shell> writes the completion script to stdout. It does not edit shell startup files.

af completion zsh > ~/.zsh/completions/_af
af completion fish > ~/.config/fish/completions/af.fish
af completion bash > ~/.local/share/bash-completion/completions/af

Output and exit code

Default output is stable multi-line key=value text. Use --output json when a script needs the old structured envelope.

  • status="ok": success, exit code 0
  • status="failed": error, exit code 1
  • status="interrupted": interrupted (SIGINT), exit code 130

Config

Config path resolution:

af --config ~/.config/af.toml config list # default path
AF_CONFIG=~/.config/af.toml af config get artifacts.dir

Supported env/config keys include:

  • AF_URL, AF_TOKEN, AF_DB
  • AF_OUTPUT
  • AF_ARTIFACT_DIR
  • AF_SCREEN_FILE
  • AF_SCREENSHOT_FILE
  • AF_PAGE_DIR

Equivalent config keys are remote.url, remote.token, connection.transport, connection.usb.device, connection.usb.local_port, connection.usb.device_port, memory.db, output.default, artifacts.dir, artifacts.screen_file, artifacts.screenshot_file, and artifacts.page_dir.

Example:

af config set remote.url "http://<IP>:<PORT>"
af config set remote.token "demo-token"
af config set memory.db "$HOME/.config/af/af.db"
af config set artifacts.dir "$HOME/.config/af/artifacts"
af config set output.default "text"

config list and config get show sensitive values such as remote.token as <redacted>.

App Install

af app install is a local adb command. It does not require the Autofish HTTP service to be installed or running.

af app install --device <ADB_SERIAL>
af app install --device <ADB_SERIAL> --version 0.5.1 --dry-run
af app uninstall --device <ADB_SERIAL>
af app uninstall --device <ADB_SERIAL> --dry-run

By default, --version current installs the App release matching the current af CLI version. The command skips the install when the same version is already present, upgrades older versions, and refuses to downgrade unless --force is passed. To reinstall, run af app uninstall first. Downloaded APKs are cached under $AF_CACHE_DIR or ~/.cache/af.

USB Connect

af connect usb is a local adb command. It reads the Autofish App hint from the release or debug package under /sdcard/Android/data/.../files/connection-hint.json; the hint contains only package/version, service port, running status, and update time.

af connect usb --device <ADB_SERIAL>
af connect usb --device <ADB_SERIAL> --local-port 18081
af connect usb --device <ADB_SERIAL> --print-only

The command writes remote.url, connection.transport=usb-forward, connection.usb.device, connection.usb.local_port, and connection.usb.device_port. It does not write remote.token; /health remains token-free.

af health includes local connection metadata in output as connection.transport, connection.device, connection.url, connection.localPort, and connection.devicePort. When transport metadata is not configured, connection.transport is unknown.

Artifact Output

Large observe payloads no longer inline image/base64 or full raw payloads in command output.

  • observe screenshot saves an image artifact and returns summary fields plus saved path.
  • observe screen --full saves the full JSON payload as an artifact.
  • observe page --field screen saves the large screen slice as an artifact and keeps light metadata inline.