Use

The command line

The hop command does from a terminal what the app does in a window. This page goes through it by task. Output shown is from real runs, trimmed where it was long.

How commands are shaped

There are three ways to say the same thing:

Words after the command fill its needed arguments in order, then the others. --name value (or --name=value) sets one by name. --flag alone means true and --no-flag false. Words left over join the last one, so hop run tower ls -la runs ls -la. A command that needs a machine and gets none uses the current machine.

$ hop do session.read --help
hop do session.read <machine> <name> [--option value…]

Read what a session shows: its last lines as plain text, scrolled-off history included.

  --machine    Machine the session is on (needed)
  --name       Session name (needed)
  --lines      How many lines from the end (default 80)

Add --json to any hop do command or short form to get its result as JSON instead of text. When something goes wrong, hop prints hop: and a sentence saying what, and exits with 1.

Machines

$ hop ls                  # your machines, and the services named for each
$ hop use tower           # make tower the current machine
$ hop ssh tower           # a plain shell there
$ hop status              # every machine: up or not, load, battery, helpers

A machine's own name means this computer when you are on it: on tower, hop status tower is hop status local, and so is its Bonjour name (tower.local). Hosts that take SSH only for git, such as github.com, are left out of the list.

hop status asks every machine at the same time. One that does not answer within 15 seconds is called down, without holding up the others.

$ hop status
local            up     Darwin   load 4.75/10   helper, windows  up 39 days,  4:12
tower            up     Linux    load 0.33/16   helper, windows  up 1:29
nas              down   nas did not answer within 15s

hop context reads what is going on on a machine in one go: its system, the apps open, the busiest programs, the folders work is happening in, its listening ports and its sessions. It is what an AI reads first to get its bearings.

$ hop context tower
system: Linux 6.12.9-arch1-1 x86_64
host: tower   user: me
uptime: up  1:41,  6 users,  load average: 1.35, 3.53, 2.26
disk: 24G free of 950G (home)

## Open apps
Desktop, firefox

## Busiest programs (%cpu %mem)
  7.2   1.0  WebKitWebProces
  4.6   0.5  krfb
  2.0   1.4  firefox
…

Sessions

Sessions are terminals that keep running on their machine (see Concepts). These commands work on this computer's sessions; add --on tower for another machine's.

$ hop sessions --on tower                       # what is running, and what each says it is doing
$ hop attach build --on tower                   # show it in this terminal (starts it if new)
$ hop new --name build --command "make all"     # start one without showing it
$ hop send build "make test" --enter            # type into it
$ hop read build --lines 20                     # what it shows, as plain text
$ hop end build
$ hop end --all tower                           # end every session there; its daemon keeps running
$ hop daemon install tower                      # let tower hold sessions
$ hop daemon status tower                       # is it there, and how many it holds

hop sessions prints a line per session: its name, its state (- when the program has not said), its title and its folder. --json gives the same as data. hop attach has no detach key: close the terminal (or its tab) and the session goes on. hop daemon stop ends every session on this computer and the background process that holds them; a terminal showing one says it ended, and does not start it again.

The same commands by address, for scripts: hop do session.read tower:session/build --lines 5, hop do session.send tower:session/build "y", hop do session.start tower --command "cargo test" --name tests.

Running a command

hop run runs one shell command on a machine and prints what it printed. It is for short things. For anything long, or that a person might want to watch, start a session instead.

$ hop run tower uname -a
Linux tower 6.12.9-arch1-1 #1 SMP PREEMPT_DYNAMIC Sat, 11 Jan 2025 09:12:44 +0000 x86_64 GNU/Linux

Files

hop cp copies a file or a whole folder between any two machines, or within one. The two machines do not have to reach each other: the copy is a tar stream that passes through the computer running hop. When the destination ends in / or is a folder that exists, what is copied goes inside it; otherwise it takes that name.

$ hop cp tower:~/.bashrc ~/from-tower/
copied tower:~/.bashrc to local:/Users/me/from-tower/ (10240 bytes sent, packed as tar)
$ hop cp tower:~/proj studio:~/backup/          # a whole folder, tower → studio

hop write writes what comes in on stdin to a file there. The file is replaced in one step, so nothing ever sees it half written, and its folder is made when missing.

$ echo "remember the milk" | hop write tower:~/notes/todo.txt
wrote 18 bytes to tower:~/notes/todo.txt

To read a file (up to 2 MB) or list a folder: hop do file.read tower:~/notes/todo.txt.

Web pages and ports

$ hop ports tower                # what is listening there, and which program
$ hop open 3000 tower            # open tower's port 3000 in your browser
$ hop open ollama tower          # … or a service named in config.toml
$ hop forward 5432 tower         # tower's port 5432 at localhost:5432 here
$ hop forward 15432:5432 tower   # … at localhost:15432 instead
$ hop up                         # run the web proxy

While hop up or the app runs, http://3000.tower.k-<key>.localhost:7080 is port 3000 on tower, in any browser on this computer, with the key hop up prints. Without the key nothing is reached, so another user of the computer or a web page cannot use your SSH through it. Pages reach it through your SSH connection; nothing is opened on tower's network.

$ hop ports tower
22
1716    kdeconnectd
3389    krdpserver
7080    hop-app
11434   ollama
47984   sunshine
…

Add --json for the same as data: {"machine": "tower", "ports": [{"port": 22, "process": ""}, …]}.

Clipboard

$ hop copy tower                 # this clipboard → tower's
$ git log -1 | hop copy tower    # stdin → tower's clipboard
$ hop paste tower                # tower's clipboard → this one (or stdout when piped)

App windows

These need the window helper, hop-windows, on the machine (see Getting started).

$ hop apps tower                 # the apps installed there, by name
$ hop windows tower              # the windows open there: id, app, title, size
$ hop shot tower:window/Godot -o godot.png   # a picture of one
$ hop elements tower:window/Godot            # its buttons, fields and text, as an outline
$ hop window tower Godot         # the app in a window of its own here, live
$ hop windows tower
1        Desktop                  2560×1440  "Whole screen"
344742   firefox                  1920×1080  "firefox"

The whole screens come first (one for each display), then the apps' windows. A window is named by id (tower:window/344742) or by its app (tower:window/Godot, that app's front window). hop shot writes a PNG to the file given with -o, to stdout when piped, or else to a new file in this folder:

$ hop shot local:window/Godot -o godot.png
godot.png: Godot — example_rs_world.tscn - Godot Engine on local: 1400 × 700 pixels. A place in it is x,y as fractions: (0,0) top left, (1,1) bottom right.

hop window tower Godot opens the app there first if it is not open, then shows it here in a window of its own, as if it were an app on this computer. Add --make-app to keep it as an app: in ~/Applications on a Mac, in the launcher on Linux.

hop stream sends a window's video, or a whole display's, to any player or tool: Matroska on stdout, H.264 inside, each frame with the time it was taken. It opens the app first when it has no window yet. A machine's name alone is its screen (where its helper can stream one: Linux for now). Only the picture goes out; sound and input stay in the Hop app for now.

$ hop stream tower:window/Godot | mpv --profile=low-latency -
$ hop stream tower | ffplay -probesize 32 -analyzeduration 0 -fflags nobuffer -    # its whole screen
$ hop stream tower:window/Godot | ffmpeg -i - -c copy godot.mkv    # record it

A window that does not change sends no new frames, so tell a player not to wait for a few seconds of video before it shows any: --profile=low-latency for mpv, the probe options above for ffmpeg's tools.

To open an app there without showing it here, or work a window with the mouse and keys by position:

$ hop do app.open tower Godot
$ hop do window.act tower 344742 '[{"t":"key","code":"F5"}]'

What Hop may do on each machine

hop permissions says, for every machine (or one), whether Hop reaches it, whether its helpers are there, and whether it may see its windows and work them, with the command that fixes what is missing. The same is in the app, under Settings → Machines.

$ hop permissions studio
studio
  reach     yes      running commands there over SSH
  sessions  yes      terminals that keep running there (the Hop daemon)
  windows   yes      its app windows, shown and worked from elsewhere (hop-windows)
  see       yes      pictures and contents of its windows and screens
  control   missing    → hop allow studio  (opens its list in System Settings on its screen)

A Mac decides for itself what Hop may do there. hop allow says what each of Hop's programs on that Mac has and lacks, and opens System Settings on its screen at the first permission still missing, with the program already in that list, so whoever is at it turns one switch. One at a time: run it again for the next.

$ hop allow studio
studio
  hop-windows  /Users/me/.local/bin/hop-windows
    Screen & System Audio Recording  allowed
    Accessibility                    missing         → System Settings is open at Accessibility on studio's screen: turn on hop-windows there
  Hop app  /Users/me/Applications/Hop.app
    Microphone                       allowed

hop-windows needs Screen & System Audio Recording to show a Mac's windows and their sound, and Accessibility (Device Control and Data Access from macOS 27) to click, type and work buttons and fields. The Hop app needs nothing to show other machines; it uses the Microphone only when you talk into an app shown from another machine. Paste from Other Apps, on a Mac that asks before a program reads the clipboard, is optional for both. You can also turn seeing or working a machine's windows off, whatever it allows; every part of Hop then refuses, AI tools included, and they cannot turn it back on:

$ hop permissions tower --off control    # no clicks or keys on tower's windows
$ hop permissions tower --on control

Buttons and fields

hop find, hop press and hop fill work an app by its real elements, named with a selector, not by where they are on the screen. They need the window helper on a Mac today; Linux and Windows are coming.

$ hop find 'local:Hop >> button'
#1 button "Machines" at (0.085, 0.030)
#2 button "All machines ▾" at (0.163, 0.030)
…
#13 button "Add-ons" at (0.948, 0.030)
#14 button "⚙" at (0.978, 0.030)
$ hop press 'studio:Calculator >> button "7"'
$ hop fill 'studio:Safari >> field "Address"' hopterm.com --enter

Put the whole address in single quotes, since it has spaces, >> and double quotes in it. Pressing brings the window to the front on its machine first. When a selector matches more than one element, press and fill refuse rather than guess: add #2 to say which. hop find only looks, so it is the safe way to try a selector. Like grep, it exits 1 when nothing matches.

Events and waiting

hop events prints changes on your machines as they happen, one a line, until Ctrl-C: machines going up and down, sessions starting, ending and changing state, windows opening, closing and changing title, ports opening and closing. --initial first prints what is already there.

$ hop events --machines tower --types port --initial
port.opened      tower:port/22
port.opened      tower:port/1716            kdeconnectd
port.opened      tower:port/11434           ollama
port.opened      tower:port/47984           sunshine
…

--machines and --types take lists separated by commas (or JSON lists). Types are whole (session.state) or kinds (session, window, port, machine): --types session.state,window. --every sets the seconds between looks (default 2). --json prints each event as a JSON line.

hop wait waits until something is so, then exits 0; it gives up after --timeout seconds (default 300) and exits 1.

$ hop wait tower:port/22 --timeout 10
tower:port/22 is open (after 0s)
$ hop wait tower:port/3999 --timeout 3
hop: tower:port/3999 was not open after 3s
$ hop wait tower:session/nope --timeout 3
hop: tower has no session named nope; wait for it as started first if it is about to be
Wait forStatesDefault
tower:session/buildworking, blocked, done, error, endeddone
tower:port/3000open, closedopen
tower:window/Godotopen, closedopen
tower:~/out.txtexists, goneexists
towerup, downup

A window, a file or an element can also be waited for until it appears:

$ hop wait 'studio:Calculator >> button "7"' --timeout 3
studio:window/Calculator >> button "7" appeared (after 0s)
$ hop wait tower:session/build done && say "build finished"
$ hop wait 'studio:Xcode >> text ~"Build Succeeded"' --timeout 600

Telling and asking you

hop notify shows a notification on a machine's screen: Notification Center on a Mac, the desktop's notifications on Linux. It is this computer's screen unless --on says another. On a Mac with the Hop app open it is Hop's own, with Hop's icon, and clicking it brings Hop forward; without the app open, macOS shows it under Script Editor's name. If you turned Hop's notifications off on that Mac, it fails with needs_permission.

$ hop notify "The export finished" --title Godot
$ hop notify "Backup done" --on studio

hop ask asks a question in a dialog and waits for the answer. It exits 0 when the answer is the first choice and 1 otherwise, or when nobody answers within --timeout seconds (default 120). That gives any script a human approval step in one line:

$ hop ask "Deploy to the VPS?" && ./deploy.sh
$ hop ask "Which build?" --choices Release,Debug,Cancel

A Mac shows up to three choices, Linux two.

Recording and replaying

Set HOP_RECORD to a file, and every hop command that does something (writes, presses, types, starts, and each wait) is added to it as a step, one JSON line each. Commands that only look are not recorded.

$ export HOP_RECORD=steps.jsonl
$ echo hi | hop write tower:~/out/a.txt
$ hop wait tower:~/out/a.txt --timeout 5
$ unset HOP_RECORD
$ cat steps.jsonl
{"args":{"base64":"aGkK","to":"tower:~/out/a.txt"},"call":"file.write"}
{"args":{"for":"tower:~/out/a.txt","timeout":5},"call":"wait"}

hop replay runs the steps again, one after another, and stops at the first that fails (exit 1) unless given --keep-going:

$ hop replay steps.jsonl
  1 file.write           ok
  2 wait                 ok
2 of 2 steps done
$ hop replay steps.jsonl --on server                        # the same steps on another machine
$ hop replay steps.jsonl --machines '{"tower": "server"}'   # tower's steps on server, the rest as they were

--on moves the steps when they name one machine besides this one, or only this one. A wait step lets a replay hold on until a window, a button or a file is there before going on. The file is plain JSON, so it can be edited, or written by hand as a list of {"call", "args"}. The same runs as the command steps.run.

Driving the Hop app

hop app asks the Hop app open on this computer to do something, as an AI tool or script would: open a tab, split, change a setting. The app listens on a file only you can open (~/.config/hop/app.sock), never on the network.

$ hop app '{"do":"state"}'       # what is open: tabs, panes, which is in front
$ hop app actions                # everything the app can do, each with an id
$ hop app run split-right
$ hop app run set:theme=midnight
$ hop app keys 'Meta+T'          # press the app's own shortcuts
$ hop app ui bar                 # what is on screen to press, each with a ref
$ hop app click e12
$ hop app search 'tower 3000'

The same are commands in the view namespace (hop do view.open tower --kind web --url http://localhost:3000/), with an --on to drive the app on another of your computers. See the reference.

The hub, phones and TVs

hop hub serves the app's window as a web page from the computer that is always on. It prints an address ending in a key. Open it on a phone, a tablet or a borrowed laptop for your machines, sessions, terminals and files, with nothing to install.

$ hop hub                              # this computer only: http://localhost:7081/#key=…
$ hop hub --listen 100.64.0.7:7081     # also other devices, at this computer's VPN address
$ hop hub --new-key                    # a new key: every address given out before stops working

Keep the hub private. Anyone with the address and key can do what you can, and it speaks plain HTTP. Reach it over something that encrypts, such as Tailscale or an SSH tunnel, not the open internet.

How it keeps to that: it listens on this computer alone unless --listen says otherwise. The key is 48 random hex digits, kept in Hop's folder where only you can read it. It sits after the # in the address, a part browsers never send to servers or put in Referer headers, and every request for your machines must carry it; it is compared in constant time. A request without it is answered without its body being read, and headers are capped, so a stranger who finds the port cannot even fill its memory. If the address got out, hop hub --new-key ends it.

Hop for iPhone and Apple TV coming reaches your machines through a computer running hop serve:

$ hop devices        # phones and TVs with Hop on this network, and which are paired
$ hop pair           # pair one, once: type the six digits it shows
$ hop serve          # keep running: paired devices reach your machines through here

All the short forms

TypeRunsWhat it does
hop run <machine> <command>shell.runRun a shell command on a machine and return what it printed
hop ports <machine>port.listThe TCP ports something is listening on, on a machine
hop windows <machine>window.listThe app windows open on a machine's screen
hop shot <machine> <window>window.lookA picture of one app window
hop elements <machine> <window>window.elementsWhat one app window holds: its buttons, fields, menus and text
hop apps <machine>app.listThe apps installed on a machine
hop statusmachine.statusWhether each machine is up, its load, battery and Hop helpers
hop write <to>file.writeWrite a file on a machine (replacing it whole)
hop cp <from> <to>file.copyCopy a file or folder from one machine to another (or within one)
hop mv <from> <to>file.moveMove or rename a file or folder on a machine
hop mkdir <folder>file.mkdirMake a folder on a machine
hop trash <path>file.trashPut a file or folder in a machine's trash, from where file.restore puts it back
hop sync <from> <to>file.syncMake a folder like another, on one machine or between two (rsync, one way)
hop eventsevent.watchStream changes on machines: sessions, windows, ports, up and down
hop wait <for>waitWait until something is so: a session done, a port open, a window, a machine
hop find <target>element.findFind elements in a window by what they are: button "Play"
hop press <target>element.pressPress an element: a button, link, checkbox or menu item
hop fill <target> <text>element.fillType into a field, replacing what it held
hop notify <text>person.notifyShow the person a notification on a machine's screen
hop ask <question>person.askAsk the person a question on a machine's screen and wait for the answer
hop permissionspermission.listWhat Hop may do on each machine, what is missing, and how to fix it
hop allowpermission.askAsk a Mac's person to let Hop see and work its windows
hop usageusage.listHow much of their plans' limits the AI programs on a machine have used
hop agentsagent.listEvery AI agent in a terminal, on every machine: working, needs you, done

Every other command is hop do <name>. The reference lists them all.