Simular

https://docs.simular.ai
Admin
Simular is an AI computer-use platform and automation framework providing tools like Sai, Agent S,...
Tokens:119,838
Snippets:1,315
Trust Score:9.6
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Run the Agent-S CLI application

Source: https://docs.simular.ai/agent-s/introduction

Starts the Agent-S framework using the CLI entry point. Execute this after installing dependencies to launch the application.

```bash
python gui_agents/cli_app.py

```

--------------------------------

### Machine.apps()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Machine

Gets all installed applications.

```APIDOC
## Machine.apps()

### Description
All installed applications.

### Method
Method

### Signature
```
apps(): App[]
```

### Returns
- **App[]** - An array of App instances.
```

--------------------------------

### Example prompts for Simulang

Source: https://docs.simular.ai/simulang/simulang-claude-code

Table of example prompts and what Claude does with each, including opening Safari, searching, scrolling, checking version, and reading API docs.

```text
/simulang open safari and go to github.com
```

```text
/simulang search for "Simular" on this page
```

```text
/simulang scroll down and take a screenshot
```

```text
/simulang what's the version of simulang?
```

```text
/simulang read the simulang-js API docs
```

--------------------------------

### Machine.app()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Machine

Gets an installed application by exact name.

```APIDOC
## Machine.app()

### Description
An installed application by exact name (no fuzzy matching). Locally this is the launcher name or path; on Android it is the package name (e.g. `com.android.chrome`).

### Method
Method

### Signature
```
app(name: string): App
```

### Parameters
#### Parameters
- **name** (string) - Required - The exact name of the application.

### Returns
- **App** - The App instance.
```

--------------------------------

### Install optional log viewer

Source: https://docs.simular.ai/simulang/simulang-claude-code

Installs the @simular-ai/simulang-log-viewer package for visual debugging. After installation, enable it with /simulang enable log view in all scripts.

```bash
npm install @simular-ai/simulang-log-viewer
```

--------------------------------

### start() method

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Loopback

Begins capturing audio. Must be called before record() or drain().

```typescript
start(): void
```

--------------------------------

### Install Agent-S dependencies with pip

Source: https://docs.simular.ai/agent-s/introduction

Installs the required dependencies for the Agent-S framework from the current directory. Run this after cloning the repository.

```bash
pip install .

```

--------------------------------

### Install simulang CLI globally

Source: https://docs.simular.ai/simulang/simulang-claude-code

Installs the @simular-ai/simulang package globally via npm. Required before initializing the Claude Code skill.

```bash
npm install -g @simular-ai/simulang
```

--------------------------------

### start()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Loopback

Begin capturing. Must be called before `record()` or `drain()`.

```APIDOC
## start()

### Description
Begin capturing. Must be called before `record()` or `drain()`.

### Method
`start()`

### Returns
- `void` - No return value.

```

--------------------------------

### Install gui-agents package

Source: https://docs.simular.ai/agent-s/quickstart

Installs the gui-agents package, which is required for Agent S.

```bash
pip install gui-agents
```

--------------------------------

### Initialize Claude Code skill

Source: https://docs.simular.ai/simulang/simulang-claude-code

Runs the simulang init-claude command to install the Claude Code skill. Must be run after installing the CLI.

```bash
simulang init-claude
```

--------------------------------

### Move action signature and usage example

Source: https://docs.simular.ai/simular-pro/simulang

Defines the Move action and shows an example moving the cursor to a textarea below a "verify insurance" anchor. Parameters other than `to` have the same definitions as in the Click action. Returns None.

```simulang
function Move({
    to: String = "",
    element: UIElement = null,
    spatialRelation: String = "",
    anchorConcept: String = "",
    prior: String = "none",
    includeInvisible: Bool = false,
    waitForLoadComplete: Bool = false,
    waitTime: Int = 0
})

```

```simulang
Move({to: "textarea", spatialRelation: "below", anchorConcept: "verify insurance"})

```

--------------------------------

### Get clipboard content

Source: https://docs.simular.ai/simular-pro/simulang

Example call that retrieves the clipboard content and assigns it to the variable clipboardContent.

```simular
var clipboardContent = GetFromClipboard({})

```

--------------------------------

### toStringWith method signature and example output

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/AccessibilitySnapshot

Renders the snapshot as indented lines with [ref=N] markers. The output example shows the format with roles, names, and refs.

```typescript
toStringWith(options?: null | SnapshotPrintOptions): string
```

```text
- window "Untitled - Notepad" [ref=0]
  - textbox "Text editor" #editor [ref=2]: "hello"
  - button "Save" [ref=5]
```

--------------------------------

### Start Perplexica with Docker Compose

Source: https://docs.simular.ai/agent-s/quickstart

Starts the Perplexica Docker containers in detached mode. Run this from the directory containing the docker-compose.yaml file.

```bash
docker compose up -d
```

--------------------------------

### Initialize Perplexica submodules

Source: https://docs.simular.ai/agent-s/quickstart

Navigates to the Perplexica directory and initializes its submodules. This is part of the Perplexica setup for web-knowledge retrieval.

```bash
cd Perplexica
git submodule update --init
```

--------------------------------

### Screenshot whole screen to clipboard

Source: https://docs.simular.ai/simular-pro/simulang

Example call that takes a screenshot of the whole screen and saves it to the clipboard.

```simular
ScreenshotToClipboard({})

```

--------------------------------

### checkAuth method with usage example

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/GroundingModel

Checks that the API key works and throws if it doesn't. Call right after creating the model so a bad key fails fast, before any UI automation has had a chance to steal focus. The example shows a try/catch that exits the process on failure.

```typescript
checkAuth(): void
```

```typescript
try { model.checkAuth() } catch { process.exit(1) }
```

--------------------------------

### Machine.foregroundApp()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Machine

Gets the application currently in the foreground.

```APIDOC
## Machine.foregroundApp()

### Description
The application currently in the foreground.

### Method
Method

### Signature
```
foregroundApp(): Instance
```

### Returns
- **Instance** - The foreground application instance.
```

--------------------------------

### Click action signature and usage examples

Source: https://docs.simular.ai/simular-pro/simulang

Defines the Click action with all parameters and shows four usage examples: clicking a new tab, command-clicking a button, double-clicking a file, and clicking relative to an anchor concept. The function signature lists defaults such as clickType "left" and position "center". Note that when using vision modes, other arguments are ignored except withCommand, clickType, and waits.

```simulang
function Click({
    at: String = "",
    mode: String = "",
    clickType: String = "left",
    withCommand: Bool = false,
    element: UIElement = null,
    spatialRelation: String = "",
    anchorConcept: String = "",
    prior: String = "none",
    position: String = "center",
    includeInvisible: Bool = false,
    waitForLoadComplete: Bool = false,
    waitTime: Int = 0
})

```

```simulang
Click({at: "new tab"})

```

```simulang
Click({at: "verify insurance button", withCommand: true})

```

```simulang
Click({at: "Styles.zip", clickType: "doubleClick"})

```

```simulang
Click({at: "slider", spatialRelation: "closest,right", anchorConcept: "pointer size"})

```

--------------------------------

### Get all news headlines from TechCrunch

Source: https://docs.simular.ai/simular-pro/examples

Opens techcrunch.com, waits 3 seconds, extracts all news headlines using ask, and prints them. Returns a success flag and the count of headlines.

```Simulang v0
function main() {
    // Open TechCrunch website
    open({url: "https://techcrunch.com"});
    wait({waitTime: 3});
    
    // Get page content
    const content = pageContent();
    
    // Ask LLM to extract all news headlines
    const headlinesResponse = ask({
        prompt: "Extract all news headlines from this TechCrunch page. Return only a JSON array of headline strings. Do not include any other text or explanation.",
        context: content
    });
    
    // Parse the JSON response
    const headlines = JSON.parse(headlinesResponse);
    
    // Print out all headlines
    console.log("TechCrunch News Headlines:");
    console.log("==========================");
    
    for (let i = 0; i < headlines.length; i++) {
        console.log(`${i + 1}. ${headlines[i]}`);
    }
    
    return {success: true, headlinesCount: headlines.length};
}
```

--------------------------------

### Read file from absolute path

Source: https://docs.simular.ai/simular-pro/simulang

Example call that reads the contents of the file at the absolute path /Users/somebody/Documents/project/links.txt.

```simular
var links = ReadFile({path: "/Users/somebody/Documents/project/links.txt"})

```

--------------------------------

### Save screenshot of whole screen

Source: https://docs.simular.ai/simular-pro/simulang

Example call that saves a screenshot of the whole screen to screenshot.png. The default directory is the desktop.

```simular
SaveScreenshot({fileName: "screenshot.png"})

```

--------------------------------

### quickSettings()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/AndroidExtras

Opens the quick-settings panel.

```APIDOC
## quickSettings()

### Description
Opens the quick-settings panel.

### Method
`quickSettings(): void`

### Parameters
None.

### Returns
`void`

```

--------------------------------

### GetCellLabel example

Source: https://docs.simular.ai/simular-pro/simulang

Gets the label of a cell in Excel, such as 'A1'.

```simular
var label = GetCellLabel({cell: cell})

```

--------------------------------

### GetCellValue example

Source: https://docs.simular.ai/simular-pro/simulang

Gets the value contained in a given cell element.

```simular
var cellValue = GetCellValue({cell: cell})

```

--------------------------------

### quickSettings method

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/AndroidExtras

Opens the quick-settings panel.

```typescript
quickSettings(): void
```

--------------------------------

### Iterate in the REPL with simulang run -i

Source: https://docs.simular.ai/simulang/simulang-primer

Use this REPL session to iterate on predicates interactively with `simulang run -i`. It shows how to get the foreground tree, snapshot it, and filter for buttons. The app must be focused before running because `fromForeground()` binds to whatever is active at the moment of the call.

```shell
$ simulang run -i
> const tree = AccessibilityTree.fromForeground()
> const root = tree.snapshot(true)
> flattenDFS(root).filter((n) => n.role === AriaRole.Button).map((n) => n.name)
[ 'Sign in', 'Cancel', '' ]

```

--------------------------------

### Screenshot table element to clipboard

Source: https://docs.simular.ai/simular-pro/simulang

Example that gets the table element on the page and saves a screenshot of it to the clipboard. Uses GetElements to retrieve the element.

```simular
var elements = GetElements({elementRoles: ["table"]})
ScreenshotToClipboard({element: elements[0]})

```

--------------------------------

### Click link with textAndScreenshot mode

Source: https://docs.simular.ai/simular-pro/examples

Opens docs.simular.ai and clicks the Introduction link in the Simulang section using textAndScreenshot mode. The instruction block is the natural-language version of the same task.

```Instruction
Open docs.simular.ai
Click the introduction link in the simulang section

```

```Simulang
function main() {
    open({url: "https://docs.simular.ai"})
    click({at: "link Introduction in the Simulang section", mode: "textAndScreenshot"})
}

```

--------------------------------

### pageContent function and usage example

Source: https://docs.simular.ai/simular-pro/simulang

Gets a JSON object containing the structural text content and base64 encoded image of the current screen. The object can be sent to a vision-language model for answering questions about the screen. Returns a dictionary with fields 'text' and 'imageFilePath'.

```simular
function pageContent({
})

```

```simular
var content = pageContent({});
var color = ask({prompt: "What is the color of this page? Return only the color:", context: content});

```

--------------------------------

### show()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Instance

Shows the instance.

```APIDOC
## show()

### Description
Shows the instance.

### Method
show

### Signature
`show(): boolean`

### Returns
- `boolean` - Whether the show operation succeeded.
```

--------------------------------

### Constructor

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/SamplesBuffer

Creates a new SamplesBuffer instance from raw PCM samples.

```APIDOC
## Constructor

### Description
Creates a new buffer from raw PCM samples.

### Signature
`SamplesBuffer(channels: number, sampleRate: number, samples: number[]): SamplesBuffer`

### Parameters
- **channels** (number) - Required - Number of interleaved channels (1 = mono, 2 = stereo).
- **sampleRate** (number) - Required - Samples per second per channel (e.g. 16000, 44100).
- **samples** (number[]) - Required - Array of f32 audio samples in `[-1.0, 1.0]`.

### Returns
`SamplesBuffer`
```

--------------------------------

### stop()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Loopback

Stop capturing. May be started again with `start()`. After stopping, call `drain()` to collect remaining buffered samples.

```APIDOC
## stop()

### Description
Stop capturing. May be started again with `start()`. After stopping, call `drain()` to collect remaining buffered samples.

### Method
`stop()`

### Returns
- `void` - No return value.

```

--------------------------------

### Invoke Simulang skill with /simulang commands

Source: https://docs.simular.ai/simulang/simulang-claude-code

Example commands to invoke the skill for common tasks like opening apps, taking screenshots, inspecting accessibility tree, clicking buttons, and typing text.

```text
/simulang open google and search for weather in sf
/simulang take a screenshot of the current screen
/simulang find all buttons on the screen using accessibility tree
/simulang click on the submit button
/simulang type "hello world" and press enter
```

--------------------------------

### Click Introduction relative to multiple anchors

Source: https://docs.simular.ai/simular-pro/examples

A complete workflow that navigates to docs.simular.ai and clicks on the Introduction link relative to different anchors. The Simulang code uses the anchorGrounding mode and wait calls between clicks. The instruction block is the natural-language version of the same task.

```Instruction
Go to docs.simular.ai
Click on Introduction closest to Getting Started
Click on Introduction closest to Simulang
Click on Introduction closest to Agent S
Click on Introduction closest to Simular

```

```Simulang
function main() {
    // Go to docs.simular.ai
    open({url: "https://docs.simular.ai"});
    
    // Click on Introduction closest to Getting Started
    click({at: "Introduction", spatialRelation: "closest", anchorConcept: "Getting Started"});
    wait({waitTime: 1});
    
    // Click on Introduction closest to Simulang
    click({at: "link Introduction", spatialRelation: "below,closest", anchorConcept: "heading Simulang", mode: "anchorGrounding"})
    wait({waitTime: 1});
    
    // Click on Introduction closest to Agent S
    click({at: "link Introduction", spatialRelation: "above,closest", anchorConcept: "heading Agent S", mode: "anchorGrounding"})
    wait({waitTime: 1});
    
    // Click on Introduction closest to Simular
    click({at: "link Introduction", spatialRelation: "below,furthest", anchorConcept: "link Blog", mode: "anchorGrounding"})
    wait({waitTime: 1});
    
    return {success: true};
}

```

--------------------------------

### Instance()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Instance

Constructor for creating an Instance object.

```APIDOC
## Instance()

### Description
Creates a new Instance object.

### Method
Constructor

### Signature
`Instance(): Instance`

### Returns
- `Instance` - The new Instance object.
```

--------------------------------

### Loopback()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Loopback

Creates a new Loopback instance for capturing a Machine's audio output.

```APIDOC
## Loopback()

### Description
Creates a new Loopback instance for capturing a Machine's audio output.

### Constructor
```
Loopback(): Loopback
```

### Returns
- `Loopback` - A new Loopback instance.

```

--------------------------------

### stop() method

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Loopback

Stops capturing audio. May be started again with start(). After stopping, call drain() to collect remaining buffered samples.

```typescript
stop(): void
```

--------------------------------

### new Screen()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Screen

Creates a new Screen instance. Typically obtained via Machine.screens, Machine.mainScreen, Machine.screenFromMouse, or Window.screen.

```APIDOC
## Constructor

### Description
Creates a new Screen instance. Typically obtained via Machine.screens, Machine.mainScreen, Machine.screenFromMouse, or Window.screen.

### Method
Constructor

### Endpoint
`Screen()`

### Parameters
None

### Returns
- **Screen** (Screen) - The created Screen instance.

### Example
```typescript
const screen = new Screen();
```
```

--------------------------------

### Create and run hello.ts with simulang run

Source: https://docs.simular.ai/simulang/simulang-primer

Create a minimal Simulang script and run it with `simulang run`. The script is an ES module with no boilerplate; the top of the file is the entry point. The output shows the expected result on macOS with Node v22.18.0.

```typescript
// hello.ts
const { platform, version } = process
console.log(`Hello from simulang on ${platform}, Node ${version}.`)

```

```bash
$ simulang run hello.ts
Hello from simulang on darwin, Node v22.18.0.

```

--------------------------------

### Get all links from the page

Source: https://docs.simular.ai/simular-pro/simulang

Gets all link elements from the current frontmost application. Uses the elementRoles parameter with the role "link".

```simulang
var allLinks = GetElements({elementRoles: ["link"]})
```

--------------------------------

### Open a URL in the default browser with App.defaultBrowser().open()

Source: https://docs.simular.ai/simulang/simulang-primer

Opens example.com in the default browser using `App.defaultBrowser().open()`. The `FocusPolicy.Steal` and `Visibility.Show` are requests, not guarantees; Chromium-based apps may ignore `Hidden`. The trailing `true` blocks for a short fixed delay, not a full network wait.

```typescript
// open-example.ts
import { App, FocusPolicy, Visibility } from '@simular-ai/simulang-js'

const instance = App.defaultBrowser().open(
  'https://example.com',
  FocusPolicy.Steal,        // ① bring the browser to the front
  Visibility.Show,          // ② don't try to hide it
  true,                     // ③ block briefly for the page to start
)

console.log('opened:', instance.pid)

```

--------------------------------

### searchRelative usage example

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/functions/searchRelative

Example usage of searchRelative with scoredSearch results for buttons and fields, using a relation that checks if a button is below and overlaps horizontally with a field.

```typescript
const buttons = window.scoredSearch(/* … */, "I'm Feeling Lucky", 0.75)
const fields = window.scoredSearch(/* … */, "Google Search", 0.75)
searchRelative(buttons, fields, (button, field) =>
  button.isBelow(field) && button.overlapsX(field)
)

```

--------------------------------

### Get cells in table as dictionary

Source: https://docs.simular.ai/simular-pro/simulang

Gets all cells contained in a table and returns them as a dictionary with element descriptions as keys. Uses returnType "strToElemDict".

```simulang
var cellDict = GetElements({elementRoles: ["cell"], spatialRelation: "containedIn", anchorRole: "table", returnType: "strToElemDict"})
```

--------------------------------

### Complete login-and-out.ts example using Simulang AccessibilityTree

Source: https://docs.simular.ai/simulang/simulang-primer

Complete Simulang script that opens automationexercise.com, verifies logged-out state, signs in using SITE_EMAIL and SITE_PASSWORD environment variables, and signs out. Uses AccessibilityTree snapshots with polling helpers (withSnapshot) to wait for UI states, and exits with code 1 on failure. Requires setting SITE_EMAIL and SITE_PASSWORD before running.

```typescript
// login-and-out.ts
import {
  AccessibilityTree,
  App,
  AriaRole,
  FocusPolicy,
  Visibility,
} from '@simular-ai/simulang-js'

const email = process.env.SITE_EMAIL
const password = process.env.SITE_PASSWORD
if (!email || !password) {
  console.error('Set SITE_EMAIL and SITE_PASSWORD before running.')
  process.exit(1)
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
const stripPUA = (s) => s.replace(/[-]/g, '').replace(/\s+/g, ' ').trim()
const labelOf = (n) => stripPUA([n.name, n.value, n.description, n.helpText].filter(Boolean).join(' '))

function flattenDFS(node, out = []) {
  out.push(node); for (const c of node.children) flattenDFS(c, out); return out
}

async function withSnapshot(tree, predicate, opts = {}) {
  const { timeoutMs = 8000, intervalMs = 250, label = 'node' } = opts
  const deadline = Date.now() + timeoutMs
  while (Date.now() < deadline) {
    const root = tree.snapshot(true)
    const hit = predicate(flattenDFS(root))
    if (hit) return hit
    await sleep(intervalMs)
  }
  throw new Error(`Timed out waiting for ${label}`)
}

const isLink = (n, re) => n.role === AriaRole.Link && re.test(labelOf(n)) && n.refId != null
const findLink = (nodes, re) => nodes.find((n) => isLink(n, re))
const SIGNUP_LOGIN = /^signup \/ login$/i
const LOGOUT = /^logout$/i

try {
  // 1. Open the site.
  const instance = App.defaultBrowser().open(
    'https://automationexercise.com', FocusPolicy.Steal, Visibility.Show, true,
  )
  await sleep(2500)
  if (!instance.isAccessible()) instance.enableAccessibility()
  const tree = AccessibilityTree.fromPid(instance.pid)

  // 2. Make sure we're logged out (self-heal from stale sessions).
  const navState = await withSnapshot(
    tree,
    (nodes) => {
      const logout = findLink(nodes, LOGOUT)
      if (logout) return { kind: 'logged-in', logout }
      if (findLink(nodes, SIGNUP_LOGIN)) return { kind: 'logged-out' }
      return null
    },
    { label: 'nav with Signup/Login or Logout' },
  )
  if (navState.kind === 'logged-in') {
    tree.activate(navState.logout.refId)
    await withSnapshot(
      tree,
      (nodes) => findLink(nodes, SIGNUP_LOGIN) && !nodes.some((n) => isLink(n, LOGOUT)),
      { label: 'logged-out state' },
    )
  }

  // 3. Click "Signup / Login".
  const loginLink = await withSnapshot(tree, (nodes) => findLink(nodes, SIGNUP_LOGIN), {
    label: '"Signup / Login" link',
  })
  tree.activate(loginLink.refId)

  // 4. Find the login form positionally and fill it.
  const { emailField, passField, loginBtn } = await withSnapshot(
    tree,
    (nodes) => {
      const hIdx = nodes.findIndex((n) => /^login to your account$/i.test(labelOf(n)))
      if (hIdx === -1) return null
      const btnIdx = nodes.findIndex(
        (n, i) => i > hIdx && n.role === AriaRole.Button && /^login$/i.test(labelOf(n)),
      )
      if (btnIdx === -1) return null
      const inputs = nodes.slice(hIdx, btnIdx).filter(
        (n) => n.role === AriaRole.Textbox && n.refId != null,
      )
      if (inputs.length < 2) return null
      return { emailField: inputs[0], passField: inputs[1], loginBtn: nodes[btnIdx] }
    },
    { label: 'login form' },
  )
  tree.setValue(emailField.refId, email)
  tree.setValue(passField.refId, password)
  tree.activate(loginBtn.refId)

  // 5. Confirm login by waiting for the Logout link, then click it.
  const logoutLink = await withSnapshot(tree, (nodes) => findLink(nodes, LOGOUT), {
    label: 'Logout link', timeoutMs: 10000,
  })
  tree.activate(logoutLink.refId)

  // 6. Confirm logout.
  await withSnapshot(
    tree,
    (nodes) => findLink(nodes, SIGNUP_LOGIN) && !nodes.some((n) => isLink(n, LOGOUT)),
    { label: 'logged-out confirmation' },
  )
  console.log('done.')
} catch (error) {
  console.error('Failed:', error instanceof Error ? error.message : error)
  process.exit(1)
}

```

--------------------------------

### Get comboBoxes to the right of text

Source: https://docs.simular.ai/simular-pro/simulang

Gets all comboBox elements to the right of the staticText with description "state selection". Uses spatialRelation, anchorRole, and anchorOverallDescription.

```simulang
var comboBoxes = GetElements({elementRoles: ["comboBox"], spatialRelation: "right", anchorRole: "staticText", anchorOverallDescription: "state selection"})
```

--------------------------------

### Machine()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Machine

Creates a new Machine instance.

```APIDOC
## Machine()

### Description
Creates a new Machine instance.

### Method
Constructor

### Signature
```
Machine(): Machine
```

### Returns
- **Machine** - A new Machine instance.
```

--------------------------------

### GetStructuredDescription: Get XML descriptions of elements

Source: https://docs.simular.ai/simular-pro/simulang

Defines the GetStructuredDescription function signature and shows a call that first gets elements with role "group" and description "group under plan progress", then gets their XML-formatted descriptions. The function returns an array of strings, each an XML-formatted description of the contents rooted at the corresponding element.

```simular
function GetStructuredDescription({
    fromElements: [UIElement]
})

```

```simular
var elements = GetElements({elementRoles: ["group"], elemOverallDescription: "group under plan progress"})
var description = GetStructuredDescription({fromElements: elements})

```

--------------------------------

### focus()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Instance

Brings the instance to the foreground and gives it focus.

```APIDOC
## focus()

### Description
Brings the instance to the foreground and gives it focus.

### Method
focus

### Signature
`focus(): boolean`

### Returns
- `boolean` - Whether the focus operation succeeded.
```

--------------------------------

### File()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/File

Constructs a new File instance.

```APIDOC
## File()

### Description
Constructs a new File instance. This is the constructor for the File class.

### Method
Constructor

### Signature
`File(): File`

### Returns
- `File` - A new File instance.

```

--------------------------------

### Drag action signature and usage examples

Source: https://docs.simular.ai/simular-pro/simulang

Defines the Drag action and shows two usage examples: dragging to a folder in Google Chrome and dragging to a folder in the same application. The `destinationApp` parameter is used when the destination is not in the same application as the origin.

```simulang
function Drag({
    to: String = "",
    element: UIElement = null,
    destinationApp: String = null
})

```

```simulang
Drag({to: "testFolder", destinationApp: "Google Chrome"})

```

```simulang
Drag({to: "testFolder"})

```

--------------------------------

### Machine.asAndroid()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Machine

Gets Android-specific extras for the machine.

```APIDOC
## Machine.asAndroid()

### Description
Phone-only operations of the underlying Android device, or `null` when this machine is the local desktop. Everything cross-platform lives on [`Machine`] and the handles it returns; this escape hatch is only for operations that have no desktop counterpart.

### Method
Method

### Signature
```
asAndroid(): null | AndroidExtras
```

### Returns
- **null | AndroidExtras** - Android-specific extras, or `null` if the machine is the local desktop.
```

--------------------------------

### Machine.fuzzyApp()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Machine

Finds an installed app by fuzzy matching.

```APIDOC
## Machine.fuzzyApp()

### Description
Find an installed app by fuzzy matching `query` against the machine’s app list (launcher names locally, package names on Android).

### Method
Method

### Signature
```
fuzzyApp(query: string): App
```

### Parameters
#### Parameters
- **query** (string) - Required - The fuzzy query string.

### Returns
- **App** - The matching App instance.
```

--------------------------------

### GetGoogleSheetCellValue

Source: https://docs.simular.ai/simular-pro/simulang

Gets the value of a cell in a Google Sheet.

```APIDOC
## GetGoogleSheetCellValue

### Description
Gets the value of a cell in a Google Sheet.

### Method
function

### Endpoint
GetGoogleSheetCellValue

### Parameters
#### Request Body
- **cell** (String) - Required - Label of a cell. Column is indicated by a capital letter and row is indicated by a number. For example "B42" is the cell at column B row 42.

### Request Example
```
var cellValue = GetGoogleSheetCellValue({cell: "B42"})
```

### Response
#### Success Response
- **Value** (String) - Value of the cell

```

--------------------------------

### Machine.focusedWindow()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Machine

Gets the window that currently has keyboard focus.

```APIDOC
## Machine.focusedWindow()

### Description
The window that currently has keyboard focus, if any. Returns `null` when nothing is focused (desktop: no focused window; Android: no visible task, e.g. the screen is off) rather than treating that as an error.

### Method
Method

### Signature
```
focusedWindow(): null | Window
```

### Returns
- **null | Window** - The focused Window, or `null` if none.
```

--------------------------------

### Directory()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Directory

Creates a new Directory instance.

```APIDOC
## Directory()

### Description
Creates a new Directory instance.

### Method
Constructor

### Signature
```
Directory(): Directory
```

### Returns
- **Directory** - A new Directory instance.
```

--------------------------------

### screen(): Screen

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Window

Gets the screen associated with the window.

```APIDOC
## screen(): Screen

### Description
Returns the screen this window lives on. Locally, it is the connected display containing the largest area of the window's bounding box; on Android, the device's screen. Throws if the window has no measurable overlap with any connected display.

### Method
screen

### Returns
Screen
```

--------------------------------

### getPos()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/AudioPlayer

Gets the current playback position in milliseconds.

```APIDOC
## getPos(): number

### Description
Playback position within the current sound in milliseconds, accounting for speed changes and seeks. Example: if you apply a speedup of _2_ to a source and `getPos()` returns _5000_ then the position in the recording is _10 seconds_ from its start.

### Returns
- `number` - Playback position in milliseconds.

```

--------------------------------

### Constructor: AskModel()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/AskModel

Creates a new AskModel instance.

```APIDOC
## AskModel()

### Description
Creates a new AskModel instance.

### Method
Constructor

### Signature
```
AskModel(): AskModel
```

### Returns
- `AskModel` - The new AskModel instance.
```

--------------------------------

### Class: Instance

Source: https://docs.simular.ai/llms.txt

A running application on a machine.

```APIDOC
## Class: Instance

### Description
A running application on a machine.

### Type
Class

### Source
https://docs.simular.ai/simulang-js/api/v13.0.0/classes/Instance.md
```

--------------------------------

### GetStructuredDescription

Source: https://docs.simular.ai/simular-pro/simulang

Function to get XML-formatted descriptions of UI elements.

```APIDOC
## GetStructuredDescription

### Description
Gets XML-formatted description of the contents in each element. Returns an array of String `[s_1, ..., s_n]`, where each `s_i` is an XML-formatted description of the contents rooted at `u_i`.

### Function Signature
```
function GetStructuredDescription({
    fromElements: [UIElement]
})
```

### Parameters
- **fromElements** (array of UIElement) - Required - An array of UIElements `[u_1, ..., u_n]`.

### Returns
- **Array of String** - Array of XML-formatted descriptions.

### Example
```
var elements = GetElements({elementRoles: ["group"], elemOverallDescription: "group under plan progress"})
var description = GetStructuredDescription({fromElements: elements})
```
```

--------------------------------

### File I/O and shelling out with Node standard library

Source: https://docs.simular.ai/simulang/simulang-primer

Use Node's standard library for file I/O and subprocesses in Simulang scripts. `import.meta.url` + `fileURLToPath` is the ES-module equivalent of CommonJS `__dirname`. The `@simular-ai/simulang-js` package also offers convenience classes (`File`, `Directory`, `Clipboard`, `System`) for cross-platform helpers, but plain `node:fs` keeps the concept count low for simple reads/writes.

```javascript
import { readdirSync, readFileSync, writeFileSync, renameSync, statSync, existsSync } from 'node:fs'
import { spawn, spawnSync } from 'node:child_process'
import { join, dirname } from 'node:path'
import { fileURLToPath } from 'node:url'

// Resolve "the directory of this script."
const HERE = dirname(fileURLToPath(import.meta.url))

// Plain I/O.
writeFileSync(join(HERE, 'out.txt'), 'hello\n')
const text = readFileSync(join(HERE, 'out.txt'), 'utf8')

// Shell out — captured output.
const result = spawnSync('python3', ['transform.py', 'in.csv'], { encoding: 'utf8' })
if (result.status !== 0) throw new Error(result.stderr)

// Fire-and-forget — open a file with the OS default app.
spawn('open', [join(HERE, 'out.txt')], { detached: true, stdio: 'ignore' }).unref()
```

--------------------------------

### GetTableColumn

Source: https://docs.simular.ai/simular-pro/simulang

Function to get a table column by header or index.

```APIDOC
## GetTableColumn

### Description
Given a header or an index String, return the column under it as [index: Element] dictionary. If the table has a column with header "Website" in cell A1, and elements elem1 and elem2 under it, then this function returns ["A2": elem1, "A3": elem2].

### Function Signature
```
function GetTableColumn({
    header: String = null, index: String = null
})
```

### Parameters
- **header** (String) - Optional - Value of column header.
- **index** (String) - Optional - Index of column header, e.g. "B42".

### Returns
- **Dictionary of [String: UIElement]** - Dictionary of all information in the column under header.

### Examples
```
var websiteColumn = GetTableColumn({header: "Website"})
```
```
var A1Column = GetTableColumn({index: "A1"})
```
```

--------------------------------

### App Class Reference

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/App

Documentation for the App class, including its constructor, properties, and the open() method.

```APIDOC
## App()

### Description
Creates a new App instance. The handle stays bound to the machine it came from.

### Method
Constructor

### Signature
`App(): App`

### Returns
- `App` - The new App instance.

## Properties

### canonicalName
- Type: `null | string`
- Required: Yes
- Description: Returns the canonical app name used for fuzzy matching (Android: the package name).

### launchTarget
- Type: `null | string`
- Required: Yes
- Description: Returns the launch target used to open the app: a name or path locally, the package name on Android.

## App.open()

### Description
Opens or switches to the application. If a URL is provided, the URL is opened with this app. `focus_policy` controls whether the app is allowed to become active/frontmost. Some applications (e.g. Chrome, Notes) ignore this request and steal focus regardless. `visibility` controls whether the app is launched hidden or shown; some applications (e.g. Chrome and other Chromium/Electron apps) ignore the hidden flag and launch visibly. Android’s activity model always launches visible and focused. When `wait_for_load_complete` is true, blocks until the instance has a window (or the platform reports launch finished), up to twenty seconds. Desktop timeouts are logged; Android treats them as errors. Pass `false` for apps that never show a window. If the app is already running, its existing windows satisfy the wait immediately — this does not wait for whatever window or tab the call may add.

### Method
open

### Signature
`open(url: undefined | null | string, focusPolicy: FocusPolicy, visibility: Visibility, waitForLoadComplete: boolean): Instance`

### Parameters
- `url` (undefined | null | string) - Required - The URL to open with this app.
- `focusPolicy` (FocusPolicy) - Required - Controls whether the app is allowed to become active/frontmost.
- `visibility` (Visibility) - Required - Controls whether the app is launched hidden or shown.
- `waitForLoadComplete` (boolean) - Required - When true, blocks until the instance has a window (or the platform reports launch finished), up to twenty seconds.

### Returns
- `Instance` - The instance of the opened app.
```

--------------------------------

### Machine.getClipboardString()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Machine

Gets the string content from the machine's clipboard.

```APIDOC
## Machine.getClipboardString()

### Description
Gets the string content from the machine’s clipboard. Returns the clipboard string if available, or `null` if the clipboard doesn’t contain string data or is empty.

### Method
Method

### Signature
```
getClipboardString(): null | string
```

### Returns
- **null | string** - The clipboard string, or `null` if not available.
```

--------------------------------

### Window()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Window

Constructor for the Window class.

```APIDOC
## Window()

### Description
Creates a new Window instance. Typically obtained via Machine.windows, Machine.focusedWindow, or Instance.windows.

### Constructor
```
Window(): Window
```

### Returns
- `Window` - A new Window instance.

```

--------------------------------

### Machine.getClipboardImage()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Machine

Gets the image content from the machine's clipboard.

```APIDOC
## Machine.getClipboardImage()

### Description
Gets the image content from the machine’s clipboard. Returns the clipboard image if available, or `null` if the clipboard doesn’t contain image data.

### Method
Method

### Signature
```
getClipboardImage(): null | Image
```

### Returns
- **null | Image** - The clipboard image, or `null` if not available.
```

--------------------------------

### Machine.focusedRoot()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Machine

Gets the root accessibility node of the focused application.

```APIDOC
## Machine.focusedRoot()

### Description
Root accessibility node of the machine’s focused application. Android has no per-application tree; this is a snapshot of everything currently shown on screen, the same as [`Machine.systemRoot`].

### Method
Method

### Signature
```
focusedRoot(): AccessibilityNode
```

### Returns
- **AccessibilityNode** - The root accessibility node.
```

--------------------------------

### Use the Instance handle returned by open()

Source: https://docs.simular.ai/simulang/simulang-primer

Shows the `Instance` handle returned by `open()`. It exposes the process ID, focus and visibility controls, and accessibility methods. Use `enableAccessibility()` to access the app's accessibility tree.

```typescript
instance.pid              // process ID
instance.isFocused()      // boolean
instance.focus()          // bring it forward
instance.hide()           // minimise
instance.isAccessible()   // does the OS expose this app's accessibility tree?
instance.enableAccessibility()

```

--------------------------------

### Machine.defaultBrowser()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Machine

Gets the machine's default web browser.

```APIDOC
## Machine.defaultBrowser()

### Description
The machine’s default web browser.

### Method
Method

### Signature
```
defaultBrowser(): App
```

### Returns
- **App** - The default browser App instance.
```

--------------------------------

### Raise a specific app with App.exactName().open(null, ...)

Source: https://docs.simular.ai/simulang/simulang-primer

Launches a specific app by exact name using `App.exactName()`. Passing `null` as the URL raises an already-running app to the foreground without changing its state.

```typescript
App.exactName('Google Chrome').open(
  null,                            // no URL — just raise the app
  FocusPolicy.Steal,
  Visibility.Show,
  false,
)

```

--------------------------------

### GetCellIndices

Source: https://docs.simular.ai/simular-pro/simulang

Function to get cell indices from an array of cell values.

```APIDOC
## GetCellIndices

### Description
Given an array of table cell values, return a corresponding array of cell indices. For example, if the table has value1 in cell A10, then `GetCellIndices(cellValues: ["value1"])` returns ["A10"].

### Function Signature
```
function GetCellIndices({
    cellValues: [String]
})
```

### Parameters
- **cellValues** (array of String) - Required - Values of the cell.

### Returns
- **Array of String** - Array of cell indices.

### Example
```
var cellIndices = GetCellIndices({cellValues: ["value1", "value2"]})
```
```

--------------------------------

### boundingBox()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Window

Returns the live bounding box of the window on the global desktop.

```APIDOC
## boundingBox()

### Description
Returns the live bounding box of the window on the global desktop, in the canonical coordinate space (OS-native units; see Machine). right and bottom are exclusive (Playwright / DOM convention). Coordinates can be negative when the window sits on a monitor that is arranged to the left of / above the primary display.

### Method
boundingBox

### Returns
- `BoundingBox` - The bounding box of the window.

```

--------------------------------

### Machine.dir()

Source: https://docs.simular.ai/simulang-js/api/v14.0.0/classes/Machine

Opens or creates a directory on the machine's filesystem.

```APIDOC
## Machine.dir()

### Description
A directory on the machine’s filesystem, opened — or created along with its parents, with `createMissing` — at `path`. Path resolution as in [`Machine.file`].

### Method
Method

### Signature
```
dir(path: string, createMissing: boolean): Directory
```

### Parameters
#### Parameters
- **path** (string) - Required - The path to the directory.
- **createMissing** (boolean) - Required - Whether to create the directory and its parents if they don't exist.

### Returns
- **Directory** - The Directory instance.
```
Tokens:
Raw