Actions

Everything that can read or change a computer is one action from this list (the tealhand-actions crate). The phone builds its cards from it, the palette in the Tealhand app on a computer searches it, the planner may only answer with it, and Tealhand Host checks every request against it. There is nothing else: no free-form commands.

The list

Action	Label	Risk	Fingerprint or PIN	Chat	Palette	Sent by	What it does
`device.status`	Show status	read	No	Yes	Yes	Phone or computer	Show CPU, GPU, memory, battery and uptime of a computer
`device.tasks`	Show running tasks	read	No	Yes	Yes	Phone or computer	List the busiest programs on a computer
`rule.add`	Add a rule	change	When it shuts down or sleeps	Yes	Yes	Phone or computer	Do something when a program closes or the GPU goes idle
`rule.list`	Show rules	read	No	Yes	Yes	Phone or computer	List the rules saved on a computer
`rule.cancel`	Cancel a rule	change	No	No	No	Phone or computer	Stop a rule so it never runs
`power.sleep`	Put to sleep	change	No	Yes	Yes	Phone or computer	Put a computer to sleep now. The answer is Ok once the helper has started, because a sleeping computer cannot answer
`power.shutdown`	Shut down	change	Yes	Yes	Yes	Phone or computer	Shut a computer down after a 60-second notice
`power.cancel`	Cancel shutdown	change	No	No	No	Phone or computer	Stop a shutdown or sleep during its 60-second notice
`device.rename`	Rename device	change	No	No	No	Phone only	Change the name of a connected device
`device.remove`	Remove device	destructive	Yes	No	No	Phone only	Remove a device so it can no longer be controlled
`remote.set`	Remote control	lower protection (on), change (off)	When turning on	No	No	Computer only	Let connected phones control this computer, or only look at it
`device.forget`	Disconnect phone	destructive	Yes (Windows Hello)	No	No	Computer only	Wipe this computer’s saved connection: the connected phone loses access at once, and the computer accepts nothing until a phone is connected again

Risk comes from the list, never from a model. read changes nothing; change changes the computer’s state or its rules; lower protection makes the computer easier to control; destructive removes access and is never offered to chat or the palette.
Chat means the planner may propose it and the commands-only ask box may run it, always with a card for anything that is not a read.
Palette means the Ctrl+K palette in the Tealhand app on a computer offers it, for that computer. A read opens Status; sleep and shut down show only when the power helper is there.
Sent by: “Phone or computer” means a phone, another of your computers (from the Tealhand app, with no fingerprint: Control your other computers from a computer), or the computer’s own Tealhand app. “Phone only” actions change the signed device list, so only the owner phone can do them. “Computer only” actions run only from the computer’s own Tealhand app; no phone and no other computer ever sends them.
A rule.add that shuts down or sleeps, and power.sleep and power.shutdown, first ask the power helper who is signed in. With another user signed in they are refused (OtherUserSignedIn); when the helper cannot be used, the answer is Internal. rule.add is refused at once, so a rule is never saved only to be dropped later.
device.rename and device.remove are carried out by the phone as a new signed device list, not as a command: Tealhand Host refuses them as requests.

Files and downloads

These actions came with shared folders. None can start from chat or the palette in M1, and files.share can be run only at the computer itself (the Tealhand app, or tealhand-host share). Reads need no card. A card names the computer, the shared folder, the file and its size.

Action	Risk	Fingerprint or PIN	Where it starts	What it does
`files.list`	read	No	Phone’s Files screen; another computer’s Files tab; an AI app	List the shared folders, or one folder in pages
`files.stat`	read	No	Phone’s Files screen; another computer’s Files tab; an AI app	Name, kind, size and date of one entry
`files.get`	read	No	Phone: open, copy to the phone, play; another computer’s Files tab (Download); an AI app	Read a range of bytes of one file
`files.put`	change	When it replaces a file	Phone: Files screen, share sheet; another computer’s Files tab (Upload files)	Upload a file into a shared folder that is not read-only
`files.mkdir`	change	No	Phone’s Files screen; another computer’s Files tab	Make a folder inside a shared folder
`files.rename`	change	When it replaces a file	Phone’s Files screen; another computer’s Files tab	Rename a file or folder in the same folder
`files.move`	change	When it replaces a file	Phone’s Files screen (Move to…); another computer’s Files tab	Move a file or folder into another folder of the same or another writable shared folder (version 10)
`files.hash`	read	No	Phone and computers, at the end of a copy (no card)	The SHA-256 of a whole file, to check a copy (version 10)
`files.delete`	destructive	Yes (not from a computer, which has no fingerprint)	Phone’s Files screen; another computer’s Files tab	Move a file or folder to the Recycle Bin or trash
`files.share`	adding: lower protection; removing and making a folder the default for downloads: change	When adding (Windows Hello)	At the computer only	Share a folder with phones, stop sharing it, or make one folder the default for downloads (or none)
`download.start`	change	No	Phone: share sheet, Downloads screen (Paste a link)	The computer downloads a web link into the shared folder the request names (any one that is not read only), or into its default for downloads when it names none
`download.cancel`	change	No	Phone’s Downloads screen, or `tealhand-host downloads cancel` at the computer	Stop a download
`download.list`	read	No	Phone’s Downloads screen, or `tealhand-host downloads` at the computer	List the downloads, with the folder each goes into

Reads that reach content (files.list, files.stat, files.get) travel on the files/1 connection and need no signature of their own after a signed opener; the others are signed commands. How: Files.

SSH access and saved commands

Opening a terminal, and saving or removing a command from a phone, need SSH access to be on at the computer (Tealhand app, or tealhand-host ssh on). It is off by default, and a phone can’t switch it on. Commands the owner already saved still run when it is off. None of these actions can start from chat or the palette in M1.

Action	Risk	Fingerprint or PIN	Where it starts	What it does
`shell.open`	lower protection	Yes (not from a computer)	Phone’s Terminal page; another computer’s Terminal tab	Open a terminal on the computer
`shell.run_key`	change	When the saved command asks for it; such a command runs only from a phone	Phone’s Terminal page; another computer’s Terminal tab	Run a saved command by its key, never by a command line
`shell.close`	change	No	Phone’s Terminal page	Close a terminal or stop a running saved command
`shell.list`	read	No	Phone’s Terminal page	List the saved commands and the recent runs, with what a finished run printed (at most 2 KiB)
`commands.add`	lower protection	Yes	Phone’s Terminal page (Add a command)	Save a command: a name, the command line, an optional folder and whether running it asks for the fingerprint. Needs SSH access on
`commands.remove`	change	No	Phone’s Terminal page (long-press, Remove)	Remove a saved command. Phones can’t run it after this. Needs SSH access on

Saved commands can also be added and removed at the computer, with tealhand-host commands or in the Tealhand app (Settings → Saved commands, which Windows Hello confirms).

Defined and run by the Host too: clip.get, clip.set, power.wake and screen.shot. The phone has no clipboard buttons any more, so the two clipboard actions are only in the list and the Host.

AI apps

An AI app on a computer (through MCP, Use Tealhand from your AI app) may use only five actions, all reads: device.status, device.tasks, files.list, files.stat and files.get. Rust checks this twice before a request leaves the computer; anything else is refused, whatever the model asks.

Parameters

Actions without parameters have none. The others, in the JSON form the planner uses:

{"action": "rule.add", "params": {"trigger": {"process_ends": {"name": "blender.exe"}}, "then": "shutdown"}}
{"action": "rule.add", "params": {"trigger": {"gpu_idle": {"minutes": 10}}, "then": "sleep"}}
{"action": "rule.cancel", "params": {"rule_id": 7}}
{"action": "device.rename", "params": {"device": "<64 hex digits>", "name": "Studio PC"}}
{"action": "device.remove", "params": {"device": "<64 hex digits>"}}
{"action": "remote.set", "params": {"enabled": false}}
{"action": "power.shutdown"}

Parameter	Rule
`process_ends.name`	1 to 260 characters; no `/` or `\`; no control or invisible characters (such as zero-width or bidi marks); no spaces at the start or end
`gpu_idle.minutes`	1 to 240
`then`	`shutdown`, `sleep` or `notify`
`device.rename` `name`	1 to 64 characters; no control or invisible characters; no spaces at the start or end
`device`	The device’s iroh key as 64 lowercase hex digits

When remote control is off

A phone, or another of your computers, may still send the read actions that don’t reach content (device.status, device.tasks, rule.list) and the cancels (rule.cancel, power.cancel, download.cancel, shell.close). Everything else from them is refused with RemoteControlOff, including reads that reach a computer’s files, screen, clipboard or a shell.

The cards

Every action has a confirmation card: a title that names the computer, one plain sentence that says what will happen, and the button’s word. It has no “What”, “When”, “On” or “Undo” labels. Two more lines show only when they help:

A later time, only when the action doesn’t happen now.
An undo line, only when it matters: removing a device, disconnecting the phone, shutting down, and deleting or replacing a file.

Some examples, for a computer named Studio PC:

Action	Title	Later time	Undo line	Button
`power.shutdown`	Shut down Studio PC	In 60 seconds	Cancel during the 60-second notice. After that, start it with its power button.	Shut down
`power.sleep`	Put Studio PC to sleep	none	none	Sleep
`rule.add` (notify)	On Studio PC, notify me when render.exe closes	When render.exe closes	none	Set rule
`rule.add` (GPU)	Put Studio PC to sleep when the GPU has been idle for 10 minutes	When the GPU has been idle for 10 minutes	none	Set rule
`device.remove`	Remove Studio PC	none	Connect it again with a new code.	Remove
`remote.set` (off)	Turn off remote control on Studio PC	none	none	Turn off
`device.forget`	Disconnect Pixel 8 from Studio PC	none	Connect it again with a new code to use it.	Disconnect
`files.delete`	Delete on Studio PC	none	Restore it from the Recycle Bin or trash on Studio PC.	Delete
`files.put` (replace)	Copy to Studio PC	none	The replaced file can’t be brought back.	Replace
`files.move`	Move on Studio PC	none	none	Move
`download.start`	Download on Studio PC	none	none	Download
`commands.add`	Save Back up photos on Studio PC	none	none	Save
`commands.remove`	Remove Back up photos from Studio PC	none	none	Remove

The device.forget card says “Rules saved on Studio PC are removed.”: forgetting wipes every rule, and any running notice, together with the saved connection. The download.start card names the link’s host, and the folder it will go into, with Change. The commands.add card shows the command line, and says whether running it asks for your fingerprint.

When busy programs are known, the sleep and shutdown cards name up to three of them (“This stops blender.exe and ffmpeg.exe.”, then “and N more”). Names from the computer are cleaned before they go on a card.

Search

The palette and the ask box without a planner search this list on the device, with no network: labels, ids and extra words such as “power off”, “suspend” or “lost phone”. Case, spaces and punctuation do not matter, and small typos are found (“shtdwn” finds Shut down).