Metadata-Version: 2.5
Name: alayout-cli
Version: 0.2.1
Summary: Inspect Android app layouts (Views and Compose) from the terminal
Project-URL: Homepage, https://github.com/hodinv/alayout-cli
Project-URL: Issues, https://github.com/hodinv/alayout-cli/issues
Project-URL: Changelog, https://github.com/hodinv/alayout-cli/releases
Author: Vasil Khodzin
License-Expression: MIT
License-File: LICENSE
Keywords: adb,android,compose,inspector,layout,terminal,tui,uiautomator
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.10
Requires-Dist: pillow>=10
Requires-Dist: rich>=13
Requires-Dist: textual>=1.0
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# alayout

Inspect the layout of a running Android app from the terminal: one-shot capture, then explore it offline.

## Installation

The package is **`alayout-cli`**, the command it installs is **`alayout`**.

**With [uv](https://docs.astral.sh/uv/)** (recommended — it downloads a suitable Python itself):

```sh
uv tool install alayout-cli
uv tool upgrade alayout-cli      # later updates
```

or with pipx: `pipx install alayout-cli`. Works the same on Windows, macOS and Linux.

**Without Python:** download the single-file binary for your OS from the
[latest release](https://github.com/hodinv/alayout-cli/releases/latest) and put it on your PATH:

| OS | File | Notes |
|---|---|---|
| Windows | `alayout-<version>-windows-x86_64.exe` | rename to `alayout.exe`; SmartScreen may ask once (More info → Run anyway) |
| macOS (Apple silicon) | `alayout-<version>-macos-arm64` | `chmod +x`, then `xattr -d com.apple.quarantine <file>` (unsigned) |
| Linux | `alayout-<version>-linux-x86_64` | `chmod +x` |

The binaries unpack themselves to the temp folder on start (about 1 s).

**Check an installation:** `alayout --version`, or `alayout --self-test SNAPSHOT_DIR` opens a saved
snapshot headless and prints e.g. `alayout 0.1.0 self-test: OK 18 views, 2 warnings, screenshot 108x240`.

You need Android platform-tools (`adb`), which is already there if Android Studio is installed.

**From a checkout** (development):

```sh
uv sync
uv run alayout --help
uv run pytest
```

Releases: see [RELEASING.md](https://github.com/hodinv/alayout-cli/blob/main/RELEASING.md).

## Usage

    alayout [-s SERIAL] [--adb PATH]                    # capture, then open the TUI on the new snapshot
    alayout capture [-s SERIAL] [--adb PATH] [-o DIR]   # save snapshot of the foreground screen
    alayout inspect [DIR]                               # open TUI; without DIR pick a saved snapshot (or n = new)
    alayout check [DIR]                                 # report layout problems (touch targets, labels, overlaps...)
    alayout diff [A] [B]                                # views added/removed/changed between two snapshots
    alayout composables [--apk PATH] [--all] [--previews] # the app's composable functions (debug APK)

`--apk PATH` (an APK, or a folder with `base.apk` and split APKs) or `--apk device` (pulls base and splits) (on `alayout`, `capture`, `inspect`) maps view ids to the layout XML files
that declare them; needs Android SDK build-tools (aapt2). The APK itself is not stored, only `apk.json`. Options may also go before the command (`alayout --apk device capture`); for an existing snapshot `--apk` is ignored.
aapt2 is looked up next to adb, in `ANDROID_HOME`/`ANDROID_SDK_ROOT`, the project's `local.properties` and the default SDK folder (Windows `%LOCALAPPDATA%/Android/Sdk`, macOS `~/Library/Android/sdk`, Linux `~/Android/Sdk`).

Snapshots go to `layout-snapshots/capture-YYYYMMDD-HHMMSS` unless `-o` is given.

adb lookup order: `--adb`, `ANDROID_HOME`, `ANDROID_SDK_ROOT`, `sdk.dir` in `local.properties`
(searched from the current directory upward), `PATH`, default SDK locations.

Data sources: `dumpsys activity top` (real View tree, including GONE views), `uiautomator dump`
(semantics incl. Compose), `screencap`. Missing sources are reported, not fatal.
In the tree, `◇` marks nodes known only from uiautomator (e.g. Compose semantics).
Inside Compose, nodes are tagged with the component they most likely are, inferred from semantics:
`⟨Button "OK"⟩`, `⟨Clickable "Row text"⟩`, `⟨IconButton "Back"⟩`, `⟨Selector⟩`, `⟨Toggle … [checked]⟩`,
`⟨TextField⟩`, `⟨Scrollable⟩`, with `(n of m similar)` for siblings of identical structure (likely the same
composable). Real composable names are not available from semantics; `alayout composables` lists the app's
composables (name, file, approximate line) from the Compose source information kept in debug APKs, as a reference.

TUI keys: arrows navigate the tree, `/` search (id, class, text, content-desc), `n`/`N` next/previous match,
`f` filter the tree to matches, `p` switch wireframe/screenshot, `s` full-screen screenshot, `o` open the real PNG in the system image viewer (selected view outlined, the rest dimmed), `c` checks list (Enter jumps to the view), `x` layout XML of the view (with `--apk`), `q` quit.
Views with warnings are marked `⚠`.

## Platforms

Windows, macOS and Linux. The screenshot preview needs a 24-bit colour terminal (Windows Terminal, iTerm2,
WezTerm, kitty, Ghostty, GNOME Terminal...); macOS Terminal.app only has 256 colours, so use `o` there to open
the real PNG. `o` uses the default image viewer (`open` on macOS, `xdg-open` on Linux); without a desktop
session (e.g. over SSH) it reports where the annotated PNG was saved instead.
