Find

Point at a target with a locator before you act on it. Use visible text when a label exists and a description when the target is easier to describe. Building a locator sends nothing: each action finds the target on the screen at that moment and waits until it is ready, up to 5 seconds by default. The examples assume you already selected a dedicated-phone session.

Find by visible text

Text matching is read by OCR. By default the match is a case-insensitive substring. Pass exact=True (Go: mobile.Exact()) for a case-sensitive exact match instead.

CLI
Python SDK
Go SDK

axilio phone find-text "Continue" -o json
axilio phone find-text "Continue" --exact -o json

find-text searches one snapshot of the screen. A miss succeeds with null in JSON output.

driver.get_by_text("Continue").tap()

if _, err := driver.GetByText("Continue").Tap(); err != nil {
    log.Fatal(err)
}

To check whether something is on screen without waiting, use count(). It reports the matches right now, zero included:

Python SDK
Go SDK

banner = driver.get_by_text("Allow notifications")
if banner.count() > 0:
    driver.get_by_text("Not now").tap()

n, err := driver.GetByText("Allow notifications").Count()
if err != nil {
    log.Fatal(err)
}
if n > 0 {
    if _, err := driver.GetByText("Not now").Tap(); err != nil {
        log.Fatal(err)
    }
}

Find every text match

Search one observed screen for a list of matches. Use a substring for a simple list or a regular expression for structured text. The two criteria are mutually exclusive.

CLI
Python SDK
Go SDK

axilio phone find-all-text "Notification" -o json
axilio phone find-all-text --pattern '\$[0-9]+\.[0-9]{2}' -o json

With neither criterion, find-all-text returns every OCR text element. Add --ocr-engine premium for a harder screen.

screen = driver.observe()
for item in screen.find_all_text(contains="Notification"):
    print(item.text)

prices = screen.find_all_text(pattern=r"\$\d+\.\d{2}")

screen, err := driver.Observe()
if err != nil {
    log.Fatal(err)
}
items, err := screen.FindAllText("Notification", "")
if err != nil {
    log.Fatal(err)
}
for _, item := range items {
    fmt.Println(item.Text)
}

Find by description

A description uses a billable vision model. When the target never appears, the action fails with a timeout.

CLI
Python SDK
Go SDK

axilio phone find "the search icon" -o json

find waits up to --timeout (10 seconds by default). A target that never appears exits with the timeout status (5). Use axilio phone tap --query "the search icon" to find and tap in one command.

from axilio.drivers.mobile import ActionTimeoutError

try:
    driver.locator(query="the search icon").tap()
except ActionTimeoutError:
    print("search icon not found")

if _, err := driver.Locator(mobile.Query("the search icon")).Tap(); err != nil {
    if mobile.IsActionTimeout(err) {
        log.Print("search icon not found")
        return
    }
    log.Fatal(err)
}

Review individual inference charges in Usage. Prefer text when a stable visible label exists.

Narrow a match

When several targets match, pick one by position, by what contains it, or by a description:

Python SDK
Go SDK

driver.get_by_text("Add to cart").nth(1).tap()

card = driver.get_by_text("Card").has(driver.get_by_text("Free shipping"))
card.first().tap()

driver.get_by_text("Delete").filter(query="the red one").tap()

if _, err := driver.GetByText("Add to cart").Nth(1).Tap(); err != nil {
    log.Fatal(err)
}

card := driver.GetByText("Card").Has(driver.GetByText("Free shipping"))
if _, err := card.First().Tap(); err != nil {
    log.Fatal(err)
}

nth counts from zero in reading order. Plain text is an OCR match; anything more, such as a description, nth, within, has, or filter, resolves with one vision-model call.

Choose the OCR engine and model

CLI
Python SDK
Go SDK

axilio phone find "the buy button" --ocr-engine premium --model anthropic/claude-haiku-4.5

find, find-all-text, observe, and tap --query accept an OCR-engine override. find-text and wait-for do not.

driver.get_by_text("Sign in", ocr_engine="premium").tap()
driver.locator(
    query="the buy button",
    model="anthropic/claude-haiku-4.5",
).tap()

Set defaults for one dedicated-phone session:

with client.session(
    "android",
    phone_id="ph_123",
    default_ocr_engine="premium",
    default_model="anthropic/claude-haiku-4.5",
) as driver:
    driver.get_by_text("Sign in").tap()
    driver.locator(query="the buy button").tap()

driver := mobile.ConnectRemote(
    controlURL,
    mobile.WithDefaultOCREngine("premium"),
    mobile.WithDefaultModel("anthropic/claude-haiku-4.5"),
)
defer driver.Close()

buy := driver.Locator(
    mobile.Query("the buy button"),
    mobile.Model("anthropic/claude-haiku-4.5"),
)
if _, err := buy.Tap(); err != nil {
    log.Fatal(err)
}

Locator actions run on the phone side over DCP Locator.* methods. The find-text and find-all-text commands and the Screen queries search one Screen.observe snapshot. None of these live phone operations is a REST endpoint.

Next steps

Tap

Act on what you found.

Wait

Wait for a target before acting.

Locator reference

Every locator action and refinement.

Models

Choose a vision model and understand inference pricing.

Drivers

Mobile driver

Models

Find by visible text

Find every text match

Find by description

Narrow a match

Choose the OCR engine and model

Next steps

Tap

Wait

Locator reference

Models

​Find by visible text

​Find every text match

​Find by description

​Narrow a match

​Choose the OCR engine and model

​Next steps

Tap

Wait

Locator reference

Models

Find by visible text

Find every text match

Find by description

Narrow a match

Choose the OCR engine and model

Next steps