# About AutoTouch

User guide for current AutoTouch builds. See the release notes when using an older version.

What is AutoTouch?

AutoTouch is a macro tool for iOS that records and replays human touches and key presses, then lets you turn them into full automations.

Record & replay — capture your taps, swipes and button presses, then play them back exactly.
Script it — everything runs as a Lua script you can read, edit and share.
Automate the screen — built-in functions for color search, image matching, OCR, text input and app control.
Control it remotely — drive AutoTouch over your LAN with the HTTP APIs.

AutoTouch requires a jailbroken device.

# Start here

I want to…	Read
Install AutoTouch and record my first script	Continue below
Write and debug Lua	Quick start and API reference
Find an image or read text	Image matching and OCR
Control a device from a computer	HTTP API guide
Resolve an error	FAQ

# How to install

On a jailbroken device, open the package manager supported by your jailbreak, such as Cydia, Sileo or Zebra.
Add the AutoTouch official repository (opens new window) and install the compatible AutoTouch package shown there.
Complete any restart or respring requested by the package manager, then open AutoTouch.
Hold Volume Down to open the control panel.

The beta repository (opens new window) contains prerelease builds. Choose a package matching your jailbreak environment; installing a rootful package on a rootless device is not interchangeable.

# How to control AutoTouch (Activator)

Hold Volume Down to open the control panel or stop a running script. Activator is optional: if it is installed and supported by your jailbreak, configure the AutoTouch action there to use a different gesture.

Throughout this guide, “hold Volume Down” means your configured control action. You do not need Activator to get started.

Screenshots below illustrate the workflow; icons and labels can vary by version.

# How to record a script

On the screen where you want to start, hold Volume Down to open the control panel.
Tap Record to begin. AutoTouch captures every touch and key press into a new script.
Hold Volume Down again to stop recording.

A new Lua script, named after its creation time, appears in the script list. You can edit, rename or play it.

# How to play a script

Hold Volume Down to open the control panel.
Tap the script you want to run.
Enable play options on the control panel if you want AutoTouch to prompt for options before running.
Enable Hold mode (the H button) to re-run the script with a single Volume Down tap each time.
To stop playback, hold Volume Down (a long press force-stops), or exit Hold mode the same way.

# How to take a screenshot

Tap Snap on the control panel, or use the normal iOS screenshot gesture (which also lets you edit it immediately).
AutoTouch captures can be saved to the AutoTouch album. The standard iOS screenshot gesture saves through iOS Photos. Import your target image into the script directory before using it with findImage; an image in Photos alone is not a script file.

# How to write a script

Tap the + button at the top-right of the local script list and choose Create a script to open the editor.
Start with alert("Hello from AutoTouch!"), or follow the Lua quick start.
Tap Save.

# Using the Function Helper while coding

The editor keyboard has Extensions, Indent and Statements buttons to help you write scripts:

Tap Extensions to browse the extended functions and insert one directly into your script.
Tap HELPER in the function list to visually determine coordinates, colors or key flags for a function.

# Managing scripts from your computer

Turn on the Web Server in AutoTouch settings and open the shown URL in a browser on your computer to manage scripts. See the HTTP APIs for programmatic control.
Or turn on the WebDAV Server and connect to the shown address with any WebDAV client.

# Organizing a project with Packages

A Package is a script project that bundles multiple scripts, files and images together. It must contain a main.lua file as its entry point.
A Package is simply a directory with an .at extension (for example MyProject.at).
A Package can be encrypted into an .ate file, which can be shared and run by a recipient. See How to encrypt scripts.

# How to encrypt scripts

Tap the accessory button of a script or package in the local script list and choose Encrypt.
Enter an encryption password — or leave it blank if you don't want one.
Tap Confirm. An .ate package is generated for either a Lua script or an .at package. Existing .lua.e files are a legacy format.

You can run encrypted scripts directly from the script list.

A password-protected package uses authenticated AES-256 encryption. Newly encrypted password packages require a version that supports the current encryption format. A no-password package uses the legacy shared format so it remains runnable across devices and app versions; it does not keep its contents confidential. Script API compatibility still depends on the installed app version.

Share the .lua file for a single script, or an .at / .ate package when it needs images and other files. Keep resource paths relative to the script so the project can move between devices. Include the required AutoTouch version and instructions for any password-protected package.

A recipient should test the script with their own screen size and app layout. Encryption does not automatically enforce payment, license checks, or device restrictions for your script.

# How to buy an AutoTouch license

Open License in AutoTouch settings, or visit license management (opens new window).
Review the available plan and validity period, then complete checkout.
If your device is not activated automatically, retrieve the purchased license and choose Activate Current Device, or enter its license key.
Confirm that the device has downloaded the license and check the displayed status and expiry date.

A transferable license activates one device at a time; moving it deactivates the previous device. Activation limits depend on ownership and account state. Follow the activation page's instructions and any displayed retry time. See Licensing questions.

Lua Guide →