CLI

The optics command creates projects, checks your setup, runs tests and starts the integration servers. This page covers Optics 1.10.5.

Commands are grouped by when you use them: getting started, running tests, integrating with other tools, and everything else. Run optics <command> --help to see the same flags in your terminal.

Global behavior#

optics [--version] [--help] <command> [options]

There's no optics version command. Use optics --version.

When you run optics with no command for the first time, it prints a welcome panel that points to optics quickstart, optics doctor and optics --help. After that, it prints a one-line reminder. Optics remembers the first run in a small marker file under ~/.optics (or $OPTICS_HOME).

If Optics can't load one of its own dependencies, every command stops with a red "Cannot start" panel. The panel shows the underlying error and the reinstall command for your environment, for example pipx reinstall optics-framework or pip install --force-reinstall optics-framework.

When a command fails unexpectedly, Optics prints Unexpected error (<type>): <message> and suggests running optics doctor. See Exit codes.

optics quickstart#

Walks you through creating your first project, installing an engine, writing config.yaml and running a test.

optics quickstart

There are no flags. The command asks these questions in order:

1. What do you want to automate? mobile or web.
2. Install the engine now? Appium for mobile; Playwright and Selenium for web. If you decline, it prints the optics setup --install command to run later.
3. Start from a sample? The contact sample for mobile, the playwright sample for web. Decline to pick an empty project or another sample.
4. Project name (default my-optics-project) and where it should live (default: the current folder). If the folder exists, it asks for another name.
5. Config questions. If the sample ships its own config.yaml, you choose whether to overwrite it. The default is yes for mobile and no for web.
6. It runs optics doctor on the new project and shows the report.
7. If the report shows no blocking problems, it offers to run your first test with optics execute.

Quickstart never runs optics dry_run. It writes the same files as optics init and optics configure.

optics init#

Creates a new project folder, either blank or copied from a sample.

optics init [name] [--path DIR] [--template NAME] [--force] [--git-init]

In a terminal without --template, Optics shows a numbered list: (Blank project), Contacts, Clock, Calendar, YouTube, Gmail Web and Playwright Web. Press Enter on a blank answer to cancel.

A blank project contains:

birch-tests/
├── config.yaml                 # commented starter config, every engine disabled
├── modules/modules.csv         # module_name,module_step,param_1,param_2,param_3
├── test_cases/test_cases.csv   # test_case,test_step
└── test_data/elements.csv      # Element_Name,Element_ID

Example:

$ optics init birch-tests --template playwright --path ~/work --git-init

Exit code 3 if the project already exists, the template name is unknown, or the name is empty.

optics configure#

Writes a project's config.yaml by asking a few questions, or opens a full editor.

optics configure [folder] [--edit]

Guided mode asks what you're automating (android, ios, web-playwright or web-selenium), then the details for that platform:

Every platform then asks whether to find elements by on-screen text with EasyOCR, and the log level. If config.yaml already exists, Optics asks before overwriting it.

Editor mode (--edit) uses these keys: ↑/↓ to move, Space to edit or toggle, S to save, Q to quit. Saving rewrites the whole file and removes your comments. Editing an engine list replaces it with enabled: true entries and drops their url and capabilities, so we recommend guided mode or a text editor for engine settings.

$ optics configure ./birch-tests

optics doctor#

Checks your Python, installed engines, device tools and project config, and tells you what to fix.

optics doctor [folder] [--check]

Doctor prints one row per check: ✅ ok, ⚠️ warning (optional or not yet needed) or ❌ failure. Each problem row has a → hint with the fix.

Only project rows can be ❌. Environment rows are ✅ or ⚠️. Without --check, doctor always exits with 0.

Doctor doesn't check Selenium capabilities, and it doesn't create any output folders.

$ optics doctor ./birch-tests --check

optics setup#

Installs the optional engines Optics needs for your platform: drivers, OCR and LLM.

optics setup [--install NAME [NAME ...]] [--list]

Names are case-insensitive. You can use an engine name (appium, ble, selenium, playwright, easyocr, pytesseract, google-vision, llm), a display name (Gemini, Google Vision) or a bundle (mobile, web, vision, all). Pin a version with a standard specifier such as appium==5.0.0 or "easyocr>=1.7,<2.0".

optics setup installs into the same Python environment as Optics. If you install Playwright, it also downloads the Chromium browser. Some environments refuse installs, for example Conda, pipx and uv tool. See Engines and extras.

The MCP server isn't an engine here. Install it with pip install "optics-framework[mcp]".

$ optics setup --install appium easyocr
$ optics setup --install web llm

Exit code 1 if a name is unknown, a version specifier is malformed (appium=5.0.0), or the install fails.

optics dry_run#

Checks a project for mistakes without running any step on a device.

optics dry_run <folder> [--runner NAME] [--use-printer | --no-use-printer]

A dry run checks that:

• Each test step names a module (or a keyword).
• Each module step names a real keyword. A typo gets a suggestion: Did you mean 'Press Element'?
• Each whole-cell ${name} is defined in your elements files.

It doesn't run any keyword or touch the device. It does load the engines in config.yaml, so the engine extras must be installed, a driver must be enabled, and its settings must be valid (for example non-empty Appium capabilities).

The output and exit codes are the same as optics execute. Dry runs write junit_output.xml to execution_output/ but no screenshots.

optics execute#

Runs every test case in a project on the real device, browser or app, and records the results.

optics execute <folder> [--runner NAME] [--use-printer | --no-use-printer]

There are no flags to pick tests or tags. To run a subset, use include or exclude in config.yaml.

What happens, in order:

1. Optics walks the whole folder and finds your files by their content (see Project files). It stops if there's no test cases file or no modules file.
2. It loads the config and stops if no driver is enabled.
3. Preflight. It checks that the first enabled driver can be reached. For Appium it connects to the server URL and, on Android, checks that adb finds a device. For Selenium it connects to the server URL. Playwright is skipped. If the check fails, Optics shows a "Cannot start" panel with the command that fixes it. Set OPTICS_SKIP_PREFLIGHT=1 to skip this check.
4. It runs Suite Setup, then each test case, then Suite Teardown. A failing test case doesn't stop the others.
5. It saves a final screenshot and page source, and runs error detection if the project has an error definitions file.

The printer shows a live tree, then a summary:

Test Suite
└── Shopper can add a backpack                                     |      1.88s |    PASS
    ├── Open the store                                             |      0.85s |    PASS
    │   └── Launch App (https://www.saucedemo.com)                 |      0.85s |    PASS

Total Test Cases: 1 | Passed: 1 | Failed: 0

When a step fails, a "Failure details" box names the test, the step and the reason:

Shopper can add a backpack → step 'Press Elemnt (//input[@id='login-button'])' — Keyword not found: Press Elemnt. Did you mean 'Press Element'? (run `optics list` to see all keywords)

Results go to execution_output/ in the project: junit_output.xml, screenshots, and logs if you turn them on. See Project files.

On-screen errors found by error detection appear in junit_output.xml as a failing test case, but they don't change the exit code.

$ optics execute ./birch-tests
$ OPTICS_SKIP_PREFLIGHT=1 optics execute ./birch-tests --no-use-printer

optics live#

Opens an interactive session where you type keywords, see each result straight away, and save what worked as a test.

optics live [folder]

The config must enable exactly one driver and at least one element source. Without a config, optics live stops with an error; there are no built-in defaults. Live runs launch_app as soon as it starts.

Type a keyword with its parameters, for example press_element ${sign_in} or enter_text ${email_field} "[email protected]". Each result appears as two lines:

  ✓ press_element ${sign_in}
     0.31s  [XPath]

Live writes its log to logs/optics_live_<time>.log and its screenshots to screenshots/session_<time>/ in the project. See Record a test for a full walkthrough.

optics serve#

Starts the HTTP API so any language or tool can drive a device through Optics.

optics serve [--host HOST] [--port PORT] [--workers N]

The server doesn't read config.yaml. Each session gets its settings from the request. Interactive API docs are at http://127.0.0.1:8000/docs. See HTTP API.

$ optics serve --port 8000

optics mcp#

Starts the MCP server, which lets an AI agent such as Claude or Cursor drive a device with Optics keywords.

optics mcp [--transport stdio|http] [--host HOST] [--port PORT]

It needs the mcp extra: pip install "optics-framework[mcp]". The all bundle doesn't include it. Without the extra, the command exits with code 1 and prints the install command. See MCP server.

optics generate#

Turns a CSV or YAML project into pytest or Robot Framework code.

optics generate <folder> [--framework pytest|robot] [--output FILE]

It writes:

• generated/Tests/<file>: the generated tests.
• generated/requirements.txt: the packages the generated code needs.
• generated/Tests/input_templates/: a copy of input_templates/ if that folder sits at the project root.

Generate has stricter needs than optics execute:

• The config file must be named exactly config.yaml.
• The project needs an elements file. Only the Element_ID column is used; fallback columns are ignored.
• Flow-control keywords (Run Loop, Condition, Evaluate and the rest) and a few others are skipped without a warning.
• Suite Setup and Suite Teardown become ordinary tests.

Exit code 3 if a required file is missing or two files define the same name. See Generate code.

$ optics generate ./birch-tests --framework robot --output smoke.robot

optics list#

Prints every keyword you can use, grouped by category.

optics list

Names are printed in snake_case. In a module, write them in Title Case with spaces: press_element becomes Press Element. Matching ignores case and spaces, so both forms work.

ActionKeyword:
  - clear_element_text
  - detect_and_press
  ...
AppManagement:
  - launch_app
  ...

For parameters and examples, see Keywords.

optics completion#

Turns on tab completion for optics in bash or zsh.

optics completion

It writes ~/.optics/optics_completion.sh and ~/.optics/optics_completion.zsh, then offers to add a source line to ~/.zshrc or ~/.bashrc, based on $SHELL. Other shells aren't supported. Restart your shell, or run source ~/.zshrc, to use it. To remove it, delete the line from your shell profile.

optics config#

Deprecated. Use optics configure.

optics config

It prints a deprecation notice, then runs guided optics configure on the current folder. There's no global config file any more: every setting lives in the project's config.yaml.

Exit codes#

Environment variables#

None of these override config.yaml. Settings for optics execute, dry_run and live come only from the project's config.yaml.

Read Data can also read any variable with ENV:<NAME>. See Flow control keywords.

Install scripts#

The install scripts put Optics in its own virtual environment under ~/.optics and add the optics command to your PATH. They don't change your system Python. Python 3.12 or later is the one prerequisite.

$ curl -fsSL https://optics-framework.org/install | sh

$ curl -fsSL https://optics-framework.org/install | sh -s -- --extra appium,easyocr

PS> irm https://optics-framework.org/install.ps1 | iex

PS> $env:OPTICS_EXTRA = "appium,easyocr"
PS> irm https://optics-framework.org/install.ps1 | iex

$ python3 -m venv .venv && . .venv/bin/activate
$ pip install "optics-framework[appium,easyocr]"

See Install Optics for a step-by-step guide.