CLI Client Commands

February 24, 2026 · View on GitHub

The flutter-skill CLI client provides command-line access to a running flutter-skill serve instance. Use it for browser automation, CI/CD pipelines, scripting, and remote access.

Prerequisites

Start a serve instance first:

flutter-skill serve https://your-app.com

The serve instance runs on http://127.0.0.1:3000 by default.

Commands

`nav` — Navigate to URL

flutter-skill nav https://google.com
flutter-skill nav https://your-app.com/login

Aliases: navigate, go

`snap` — Accessibility Tree Snapshot

Returns a compact semantic representation of the page — 99% fewer tokens than a screenshot.

flutter-skill snap

Alias: snapshot

`screenshot` — Take Screenshot

flutter-skill screenshot                  # Saves to /tmp/screenshot.jpg
flutter-skill screenshot /tmp/login.jpg   # Custom path

Alias: ss

`tap` — Tap Element

Three targeting modes:

flutter-skill tap "Login"           # By visible text
flutter-skill tap e15                # By element ref (from snap)
flutter-skill tap 200 300            # By coordinates (x y)

`type` — Type Text

Types text via keyboard simulation:

flutter-skill type "hello@example.com"
flutter-skill type "my search query"

`key` — Press Key

flutter-skill key Enter
flutter-skill key Tab
flutter-skill key a control        # Ctrl+A (select all)
flutter-skill key c meta           # Cmd+C (copy on macOS)

Alias: press

`eval` — Execute JavaScript

flutter-skill eval "document.title"
flutter-skill eval "document.querySelectorAll('a').length"
flutter-skill eval "window.location.href"

Alias: js

`title` — Get Page Title

flutter-skill title
# Output: My App - Dashboard

`text` — Get Visible Text

flutter-skill text

`hover` — Hover Element

flutter-skill hover "Menu Item"
flutter-skill hover "Dropdown"

`upload` — Upload File

flutter-skill upload "input[type=file]" /path/to/image.png
flutter-skill upload auto /path/to/document.pdf    # Auto-detect input

`tools` — List Available Tools

flutter-skill tools
# Output:
# navigate
# snapshot
# screenshot
# tap
# ...
# 246 tools

`call` — Call Any Tool Directly

For tools not covered by shorthand commands:

flutter-skill call page_summary
flutter-skill call fill '{"selector": "#email", "value": "test@example.com"}'
flutter-skill call set_viewport '{"width": 375, "height": 812}'
flutter-skill call emulate_device '{"device": "iPhone 14"}'

`wait` — Wait (ms)

flutter-skill wait 2000    # Wait 2 seconds
flutter-skill wait          # Default: 1000ms

Configuration

Port and Host

# Via flags
flutter-skill tap "Login" --port=8080
flutter-skill snap --host=192.168.1.100 --port=4000

# Via environment variables
export FS_PORT=8080
export FS_HOST=192.168.1.100
flutter-skill tap "Login"

Priority: environment variables override flags.

Serve Startup Options

flutter-skill serve https://your-app.com --port=8080 --host=0.0.0.0

Scripting Examples

flutter-skill nav https://app.example.com/login
flutter-skill tap "Email"
flutter-skill type "user@example.com"
flutter-skill tap "Password"
flutter-skill type "secretpass"
flutter-skill tap "Sign In"
flutter-skill wait 2000
flutter-skill screenshot /tmp/after-login.jpg

CI/CD Pipeline

#!/bin/bash
set -e

# Start serve in background
flutter-skill serve https://staging.example.com &
sleep 3

# Run test sequence
flutter-skill snap
flutter-skill tap "Get Started"
flutter-skill wait 1000
flutter-skill screenshot /tmp/ci-test.jpg
flutter-skill title

# Cleanup
kill %1

Batch Testing with `call`

# Execute multiple actions in one call
flutter-skill call execute_batch '{
  "actions": [
    {"type": "fill", "target": "input:Email", "value": "test@example.com"},
    {"type": "fill", "target": "input:Password", "value": "password123"},
    {"type": "tap", "target": "button:Login"}
  ]
}'

Troubleshooting

"flutter-skill serve not running"

The CLI client connects to an existing serve instance. Make sure it's running:

flutter-skill serve https://your-app.com

Connection refused

Check the port:

# Default port
curl http://127.0.0.1:3000/tools/list

# Custom port
curl http://127.0.0.1:8080/tools/list

Timeout on commands

The default timeout is 30 seconds. For slow operations, use call with longer timeouts or break into smaller steps.

Command Reference

Command	Description	Arguments
`nav <url>`	Navigate to URL	URL (required)
`snap`	Accessibility tree snapshot	—
`screenshot [path]`	Take screenshot	Path (optional, default: `/tmp/screenshot.jpg`)
`tap <target>`	Tap element	Text, ref (`e15`), or coordinates (`x y`)
`type <text>`	Type via keyboard	Text (required)
`key <key> [mod]`	Press key	Key name, optional modifier
`eval <js>`	Execute JavaScript	Expression (required)
`title`	Get page title	—
`text`	Get visible text	—
`hover <text>`	Hover element	Text (required)
`upload <sel> <file>`	Upload file	Selector + file path
`tools`	List all tools	—
`call <tool> [json]`	Call any tool	Tool name + optional JSON args
`wait [ms]`	Wait	Milliseconds (default: 1000)