# Boot an instance and open an ADB tunnel (defaults: --connect=true).
lim android create

# Auto-delete the pod when this CLI process exits, and pin to a region with a label.
lim android create --rm --region us-west --label app=demo --label session=docs

# Pre-install a local APK (uploaded to Asset Storage first, MD5-deduplicated).
lim android create --install ./build.apk

# Reference an asset that's already in storage by name.
lim android create --install-asset chrome-stable

import { Limrun } from '@limrun/api';

const lim = new Limrun();   // reads LIM_API_KEY from the environment

const instance = await lim.androidInstances.create({
  wait: true,            // resolve only after status.state === 'ready'
  reuseIfExists: true,   // return the existing match instead of creating a new pod
  metadata: { labels: { app: 'demo', session: 'docs' } },
  spec: {
    region: 'us-west',           // optional; otherwise picked by clues + availability
    inactivityTimeout: '10m',    // 1m, 10m, 3h, ...
    hardTimeout: '0',            // '0' = no hard cap
    clues: [{ kind: 'OSVersion', osVersion: '15' }],   // '13' | '14' | '15'
  },
});

console.log(instance.metadata.id, instance.status.state);

import (
    "context"
    "os"
    limrun "github.com/limrun-inc/go-sdk"
    "github.com/limrun-inc/go-sdk/option"
    "github.com/limrun-inc/go-sdk/packages/param"
)

lim := limrun.NewClient(option.WithAPIKey(os.Getenv("LIM_API_KEY")))

inst, _ := lim.AndroidInstances.New(ctx, limrun.AndroidInstanceNewParams{
    Wait:          param.NewOpt(true),
    ReuseIfExists: param.NewOpt(true),
    Metadata: limrun.AndroidInstanceNewParamsMetadata{
        Labels: map[string]string{"app": "demo", "session": "docs"},
    },
    Spec: limrun.AndroidInstanceNewParamsSpec{
        Region:            param.NewOpt("us-west"),
        InactivityTimeout: param.NewOpt("10m"),
        HardTimeout:       param.NewOpt("0"),
        Clues: []limrun.AndroidInstanceNewParamsSpecClue{
            {Kind: "OSVersion", OsVersion: param.NewOpt("15")},
        },
    },
})

from limrun_api import Limrun

lim = Limrun()  # reads LIM_API_KEY

instance = lim.android_instances.create(
    wait=True,
    reuse_if_exists=True,
    metadata={"labels": {"app": "demo", "session": "docs"}},
    spec={
        "region": "us-west",
        "inactivity_timeout": "10m",
        "hard_timeout": "0",
        "clues": [{"kind": "OSVersion", "os_version": "15"}],
    },
)

# Local APK uploaded to Asset Storage on the fly, then installed.
lim android create --install ./build.apk

# Multiple unrelated apps; each --install becomes its own install group.
lim android create --install ./app-a.apk --install ./app-b.apk

# Already in Asset Storage? Reference it by name instead.
lim android create --install-asset chrome-stable

const instance = await lim.androidInstances.create({
  wait: true,
  reuseIfExists: true,
  spec: {
    initialAssets: [
      // One asset by name (already uploaded via assets.getOrUpload)
      { kind: 'App', source: 'AssetName', assetName: 'my-app-build.apk' },

      // Direct URLs, no Asset Storage upload required
      { kind: 'App', source: 'URL',
        url: 'https://example.com/builds/123.apk' },
      { kind: 'App', source: 'URLs',
        urls: ['https://example.com/base.apk', 'https://example.com/config.apk'] },

      // Reference by asset ID (when you already have one)
      { kind: 'App', source: 'AssetIDs',
        assetIds: ['asset_01j...'] },
    ],
  },
});

inst, _ := lim.AndroidInstances.New(ctx, limrun.AndroidInstanceNewParams{
    Wait:          param.NewOpt(true),
    ReuseIfExists: param.NewOpt(true),
    Spec: limrun.AndroidInstanceNewParamsSpec{
        InitialAssets: []limrun.AndroidInstanceNewParamsSpecInitialAsset{
            // One asset by name
            {
                Kind:      "App",
                Source:    "AssetName",
                AssetName: param.NewOpt("my-app-build.apk"),
            },
            // Direct URL
            {
                Kind:   "App",
                Source: "URL",
                URL:    param.NewOpt("https://example.com/builds/123.apk"),
            },
            // Multiple URLs as one install group
            {
                Kind:   "App",
                Source: "URLs",
                URLs:   []string{"https://example.com/base.apk", "https://example.com/config.apk"},
            },
            // Reference by asset ID
            {
                Kind:     "App",
                Source:   "AssetIDs",
                AssetIDs: []string{"asset_01j..."},
            },
        },
    },
})

instance = lim.android_instances.create(
    wait=True,
    reuse_if_exists=True,
    spec={
        "initial_assets": [
            # One asset by name (already uploaded via assets.get_or_upload)
            {"kind": "App", "source": "AssetName", "asset_name": "my-app-build.apk"},

            # Direct URLs
            {"kind": "App", "source": "URL",
             "url": "https://example.com/builds/123.apk"},
            {"kind": "App", "source": "URLs",
             "urls": ["https://example.com/base.apk", "https://example.com/config.apk"]},

            # Reference by asset ID
            {"kind": "App", "source": "AssetIDs",
             "asset_ids": ["asset_01j..."]},
        ],
    },
)

await lim.androidInstances.create({
  wait: true,
  spec: {
    initialAssets: [
      // From Asset Storage by name
      { kind: 'App', source: 'AssetNames',
        assetNames: ['base.apk', 'config.xxhdpi.apk', 'config.en.apk'] },

      // Or from any HTTPS URLs the daemon can reach
      { kind: 'App', source: 'URLs',
        urls: [
          'https://example.com/base.apk',
          'https://example.com/config.xxhdpi.apk',
          'https://example.com/config.en.apk',
        ] },
    ],
  },
});

inst, _ := lim.AndroidInstances.New(ctx, limrun.AndroidInstanceNewParams{
    Wait: param.NewOpt(true),
    Spec: limrun.AndroidInstanceNewParamsSpec{
        InitialAssets: []limrun.AndroidInstanceNewParamsSpecInitialAsset{
            {
                Kind:       "App",
                Source:     "AssetNames",
                AssetNames: []string{"base.apk", "config.xxhdpi.apk", "config.en.apk"},
            },
            {
                Kind:   "App",
                Source: "URLs",
                URLs: []string{
                    "https://example.com/base.apk",
                    "https://example.com/config.xxhdpi.apk",
                    "https://example.com/config.en.apk",
                },
            },
        },
    },
})

lim.android_instances.create(
    wait=True,
    spec={
        "initial_assets": [
            {"kind": "App", "source": "AssetNames",
             "asset_names": ["base.apk", "config.xxhdpi.apk", "config.en.apk"]},

            {"kind": "App", "source": "URLs",
             "urls": [
                 "https://example.com/base.apk",
                 "https://example.com/config.xxhdpi.apk",
                 "https://example.com/config.en.apk",
             ]},
        ],
    },
)

{
  kind: 'Configuration',
  configuration: {
    kind: 'ChromeFlag',
    chromeFlag: 'enable-command-line-on-non-rooted-devices@1',
  },
}

limrun.AndroidInstanceNewParamsSpecInitialAsset{
    Kind: "Configuration",
    Configuration: limrun.AndroidInstanceNewParamsSpecInitialAssetConfiguration{
        Kind:       "ChromeFlag",
        ChromeFlag: "enable-command-line-on-non-rooted-devices@1",
    },
}

{
    "kind": "Configuration",
    "configuration": {
        "kind": "ChromeFlag",
        "chrome_flag": "enable-command-line-on-non-rooted-devices@1",
    },
}

lim android screenshot screen.png
lim android screenshot screen.png --id <ID>

const shot = await client.screenshot();
// { dataUri: 'data:image/png;base64,iVBORw0K...' }

import { writeFileSync } from 'node:fs';
const png = Buffer.from(shot.dataUri.replace(/^data:image\/\w+;base64,/, ''), 'base64');
writeFileSync('screen.png', png);

lim android record start --quality 5

# ...drive the UI...

# Download to a local file (default: timestamped mp4 in cwd).
lim android record stop -o demo.mp4

# Or hand the bytes to a presigned upload URL.
lim android record stop --presigned-url https://example.com/upload

await client.startRecording({ quality: 5 });

// ...drive the UI...

const url = await client.stopRecording({ localPath: '/tmp/demo.mp4' });
// url is also returned so you can re-fetch later

# Print the raw XML.
lim android element-tree

# Or get the parsed nodes as JSON (agent-friendly).
lim android element-tree --json

const tree = await client.getElementTree();
// tree.xml    raw UIAutomator XML
// tree.nodes  flattened AndroidElementNode[]

# Local path: uploaded to Asset Storage first, then installed.
lim android install-app ./build.apk

# Remote URL: passed straight to the daemon.
lim android install-app https://example.com/build.apk --id <ID>

// Local file: upload once, then install via the returned signed URL.
const asset = await lim.assets.getOrUpload({ path: './build.apk' });
await client.sendAsset(asset.signedDownloadUrl);

// Or install straight from a public URL.
await client.sendAsset('https://example.com/build.apk');

// Default request timeout is 120s. Pass a custom timeout for larger APKs.
await client.sendAsset(asset.signedDownloadUrl, 180_000);

# Find by text, return up to 5 matches as JSON.
lim android find-element --text "Sign In" --limit 5 --json

# Find by resource id; defaults to up to 20 matches.
lim android find-element --resource-id com.example:id/submit

# Filter for clickable buttons that are enabled.
lim android find-element --class-name android.widget.Button --clickable --enabled

const r = await client.findElement({ text: 'Chrome' }, 5);
// { count: 1, elements: [ { ... AndroidElementNode } ] }

# Tap by selector (preferred). Pass any selector flag from the table above.
lim android tap-element --resource-id com.example.app:id/login
lim android tap-element --text "Sign In"

# Tap by raw coordinates (fallback).
lim android tap 374 219

# Type into the focused field, or into a specific input via selector / coords.
lim android type "hello"
lim android type "docs sandbox" --class-name android.widget.EditText
lim android type "hello" --x 120 --y 340

# Hardware and IME keys; --modifier is repeatable.
lim android press-key HOME
lim android press-key BACK
lim android press-key enter
lim android press-key a --modifier shift

// Tap by selector (preferred)
await client.tap({ selector: { resourceId: 'com.example.app:id/login' } });
await client.tap({ selector: { text: 'Chrome' } });

// Tap by coords (fallback)
await client.tap({ x: 374, y: 219 });

// Type into the currently focused field, or into a specific input
await client.setText(undefined, 'hello');
await client.setText(
  { selector: { className: 'android.widget.EditText' } },
  'docs sandbox',
);

// Hardware and IME keys
await client.pressKey('HOME');                 // returns { key: 'KEYCODE_HOME' }
await client.pressKey('BACK');
await client.pressKey('ENTER');
await client.pressKey('a', ['shift']);         // modifiers: shift, ctrl/control, alt/option, meta/command/cmd, sym, fn

# Scroll the screen. --amount defaults to 300 in the CLI.
lim android scroll down --amount 500
lim android scroll up

# Scroll inside a specific element by selector or coords.
lim android scroll down --resource-id com.example:id/list --amount 500
lim android scroll up --x 120 --y 500 --amount 250

// SDK amount defaults to 6.
await client.scrollScreen('down', 6);
await client.scrollScreen('up');
await client.scrollScreen('left', 4);
await client.scrollElement(
  { selector: { className: 'android.widget.ScrollView' } },
  'down',
  3,
);

lim android open-url https://example.com
lim android open-url myapp://orders/42 --id <ID>

await client.openUrl('https://example.com');           // launches in the default browser
await client.openUrl('myapp://orders/42');             // routes to your app's deeplink handler

lim android list                       # all ready instances (use --all for every state)
lim android list --label-selector user=alice
lim android delete <ID>                # tear down a specific instance
lim android delete                     # tear down the last-created instance

// Single instance
await lim.androidInstances.delete(instance.metadata.id);

// Or every instance matching a label
for await (const inst of lim.androidInstances.list({
  labelSelector: `user=${userId}`,
  state: 'ready',
})) {
  await lim.androidInstances.delete(inst.metadata.id);
}

// Single instance
_ = lim.AndroidInstances.Delete(ctx, inst.Metadata.ID)