Commands

Every command prints one JSON object. Add --pretty to read it yourself. latch help COMMAND lists a command's options, and latch help COMMAND --examples shows how to call it.

ForMeans
HostYou, the owner, run it.
AgentYour agent runs it, to ask a host for something.

Commands marked "Owner only" work from your own computers, never for an agent.

Choosing a host

--host NAME sends an Agent command to that host, over the encrypted connection between the two computers. Without it, the command goes to the host LATCH_HOST names; else to this computer, if it hosts; else to your only host. With several hosts and none named, it stops with host_required. --host default is the host latch hosts default NAME saved on this computer, or for this agent.

rules, vault and audit work on this computer's own host, or on another of your hosts with --host NAME. Bare latch status reports this computer and ignores LATCH_HOST; latch status --host NAME reports another host, for you only, never for an agent. latch browser setup runs only on the computer you're at: with --host it stops with host_not_supported.

Host
terminal
latch rules show --host my-pi
Agent
terminal
latch browser open --host my-mac https://example.com

Set up

CommandForWhat it does, and an example
latch setupHostSet this machine up, step by step, at a terminal.
latch loginHostLog this machine or agent in to Plow: create its key if missing and register it.
latch logoutHostLog this machine out of Plow.
latch statusHost AgentPrint this machine, its login and account, and the account's hosts.
latch devicesHostList this account's machines, online or not, or remove one.
latch devices removeHostRemove a machine and sign out the Plow login it registered with. Owner only.
Remove the old Pi without a prompt: latch devices remove old-pi --yes
latch hosts defaultHostThe host --host default names: print it, save NAME, or clear it. Saved, use it with --host default (or LATCH_HOST=default); commands without --host are unchanged. Kept in this state folder, for this machine or agent alone; it reaches no host you couldn't name yourself.
Use mbp when --host default is given: latch hosts default mbp
latch updateHost AgentInstall the newest latch, or the build TAG names.
latch appHostOpen the Plow Latch app this latch belongs to (macOS).
latch helpHostHelp for a command, its examples, or every command as JSON.
Help for one command: latch help browser open
latch skillAgentPrint SKILL.md, which teaches an agent how to use latch.

Run a host

CommandForWhat it does, and an example
latch serveHostRun this machine as a host.
latch stopHostStop the host on this state folder; its state is kept.
latch dashboardHostView the running host; Ctrl-C closes only the view.
latch logsHostThe host's diagnostics (serve.log).
Follow the host's log: latch logs --follow
latch settings setHostSave a setting for this machine's host; needs no login, host or restart.
Keep this Mac awake while plugged in, for its host: latch settings set --keep-awake on

Agents

CommandForWhat it does, and an example
latch agentsHostList your agents, with their lines and Plow status. Owner only.
latch agents showHostShow one agent, by its uid or its exact name. Owner only.
One agent, by its name: latch agents show Scout
latch agents catalogHostThe kinds of cloud agent Plow can run, for agents new --cloud. Owner only.
latch agents start-by-textHostShow how to start a cloud agent by texting Plow. Owner only.
latch agents linesHostPlow's phone lines, and which are free for a new agent. Owner only.
latch agents newHostCreate an agent on a free phone line. Owner only.
An agent you run yourself: latch agents new --own --token-file scout.token --name Scout --line +15550000002
latch agents cardHostSave the contact card of an agent's line, by the agent's uid or exact name. Owner only.
Save an agent's contact card: latch agents card Willow --output willow.vcf
latch agents removeHostRemove an agent, by its uid or its exact name. Owner only.
Remove an agent without asking: latch agents remove Scout --yes

Programs and files

CommandForWhat it does, and an example
latch execAgentRun one program on a host, inside its sandbox.
Run a shell line on the Pi: latch exec --host pi -- sh -c 'uname -a; ls'
latch file getAgentCopy a file from the host to this machine.
Fetch a build log from the Pi: latch file get --host pi build/log.txt ./log.txt
latch file putAgentCopy a file from this machine to the host.
Send a script into ~/scripts on the Pi: latch file put --host pi ./check.sh scripts/

Browser

CommandForWhat it does, and an example
latch browser openAgentStart a new browser session and load URL.
Open a page in a new session: latch browser --host mac open https://shop.example/
latch browser observeAgentA fresh element list (snapshot), the page's first text, and the tabs.
See the page: latch browser --host mac observe
latch browser textAgentThe page's text.
Read the page: latch browser --host mac text
latch browser screenshotAgentA PNG of the page, written to a file on this machine.
Capture the page: latch browser --host mac screenshot page.png
latch browser doAgentRun a plan of up to 10 browser steps, in order.
Type, then click and check where it led: latch browser --host mac do 'type e3 "Ada Lovelace"' 'click e7 -> path: /cart'
latch browser actAgentRun one browser step on a ref from the last page.
Click and check the result: latch browser --host mac act click e7 --check 'text: Added to cart'
latch browser handoffAgentHand this session to the owner, and wait until they hand it back.
Ask the owner to solve a CAPTCHA: latch browser --host mac handoff --reason captcha
latch browser findAgentCandidate refs by role and exact name; never acts.
Find the download button: latch browser --host mac find --role button --name Download
latch browser waitAgentWait for an element's state, text or a path, with a deadline.
Wait for a confirmation: latch browser --host mac wait --text Saved
latch browser gotoAgentLoad URL in the session's active tab.
Load the next page: latch browser --host mac goto https://shop.example/cart
latch browser tab newAgentA new tab, on URL or blank; it becomes the active one.
Open a page in a new tab: latch browser --host mac tab new https://docs.example/
latch browser tab switchAgentMake tab T (such as t2) the active one.
Go back to the first tab: latch browser --host mac tab switch t1
latch browser tab closeAgentClose tab T, or the active one.
Close the second tab: latch browser --host mac tab close t2
latch browser dialogAgentAnswer the open dialog.
Accept a confirm dialog: latch browser --host mac dialog accept
latch browser evalAgentRun JavaScript from a file in the page.
Run a check script: latch browser --host mac eval --script-file check.js
latch browser uploadAgentPut a file from this machine into a file input, by its ref.
Attach an invoice: latch browser --host mac upload e4 ./invoice.pdf
latch browser downloadsAgentThe session's downloads, as handles (d1, d2, …).
List the downloads: latch browser --host mac downloads
latch browser download getAgentWrite download D (such as d1) to a file here.
Bring a report here: latch browser --host mac download get d1 --output report.csv
latch browser fillAgentFill a page's fields from a vault item.
Sign in with the login saved for the page's site: latch browser --host mac fill --field username=e4 --field password=e5 --press e6
latch browser sessionsAgentYour open sessions, without their ids.
List your sessions: latch browser --host mac sessions
latch browser closeAgentEnd the session, deleting its cookies and logins.
End this session: latch browser --host mac close
latch browser setupHostDownload and verify a browser engine into this machine's state folder. Owner only.

Vault

CommandForWhat it does, and an example
latch vault listHost AgentThe items' metadata, a login's username included (never a secret value).
The items saved for a site: latch vault --host mac list --site crateandbarrel.com
latch vault showHostOne item's metadata and its non-secret values (never a secret one). Owner only.
Show an item: latch vault --host mac show v3
latch vault addHostAdd an item to the vault. Owner only.
Add a login with its password as JSON on stdin: latch vault add --kind login --title Shop --site shop.example --field username=ada --stdin
latch vault editHostChange an item's title, sites or fields, at its current revision. Owner only.
Change a login's password, given as JSON on stdin: latch vault edit v1 --revision 2 --stdin
latch vault linkHost AgentAdd an item from your phone, through a one-time link.
An agent asks its owner for a login, then sends them the url: latch vault --host mac link --kind login --title Shop --site shop.example --field username=owner@example.com
latch vault link-stateHost AgentWhether a phone link is still pending, saved (with the new item's id) or expired; never a value.
Whether the owner has saved the login yet: latch vault --host mac link-state l3f09a2c1
latch vault removeHostRemove an item at its current revision. Owner only.
Remove an item: latch vault --host mac remove v3 --revision 1
latch vault importHostImport another password manager's export. Owner only.
Import a 1Password export: latch vault --host mac import export.1pux

Rules

CommandForWhat it does, and an example
latch rules setHostReplace the rules with TEXT, with the text of --file F (- reads stdin), or with a preset's. Owner only.
Let agents read mail, never send it: latch rules set 'Agents may search my mail but never send any.'
latch rules editHostChange the rules in $EDITOR; saved only if they did not change meanwhile. Owner only.
Edit one agent's rules: latch rules edit --agent ada
latch rules clearHostRemove the rules. Owner only.
latch rules showHostThe rules for every agent and each agent's own, with their revisions. Owner only.
latch rules tryHostPreview the gatekeeper's verdict on a request, without running it. Owner only.
Would Penny be allowed to build the site? latch rules try --agent Penny -- exec --write ~/site -- npm run build

Connectors

CommandForWhat it does, and an example
latch plugins enableHostTurn a connector on, if its setup succeeds. Owner only.
Turn Google on here: latch plugins enable google
latch plugins disableHostTurn a connector off. Owner only.
Turn Google off here: latch plugins disable google
latch google -- COMMANDAgentRun one allowed command on a host's Google account. Calendar: calendars, conflicts, create, delete, event, events, freebusy, move, respond, search, update. Gmail: archive, attachment, drafts create, drafts delete, drafts forward, drafts get, drafts list, drafts reply, drafts reply-all, drafts send, drafts update, forward, get, labels list, mark-read, messages modify, messages search, reply, reply-all, search, send, thread get, unread.
Search one account's mail: latch google --host mac --account ada@example.com -- gmail search 'from:grace newer_than:7d'
latch messages searchAgentSearch messages for PHRASE, newest first.
Find a sign-in code texted in the last ten minutes: latch messages search --host mac --since 10m code
latch messages threadAgentOne conversation, oldest first, ending with its newest message.
The direct conversation with one handle: latch messages thread --host mac --with +15550000001
latch messages chatsAgentConversations, most recently active first, with who is in them.
Recent group chats: latch messages chats --host mac --kind group
latch messages unrepliedAgentDirect conversations whose newest message is inbound: candidates, not proof a reply is owed.
Unanswered in the last day: latch messages unreplied --host mac --within 24h
latch contacts searchAgentFind people by name, nickname or organization.
Find a person's handles: latch contacts search --host mac Ada
latch contacts lookupAgentThe names on cards with each handle (more than one: ambiguous).
Who is this number? latch contacts lookup --host mac +15550000001

Audit

CommandForWhat it does, and an example
latch auditHostRead a host's sealed audit log. Owner only.
latch audit verifyHostCheck every record's place in the chain, without the key.
latch audit rotate-keyHostSeal new records under a new key.
latch audit judgeHostShow what the gatekeeper asked Plow for one judgment, and the answer. Owner only.
See what the gatekeeper was asked and answered: latch --pretty audit judge REQUEST
latch audit shotHostSave a browser screenshot an audit record names. Owner only.
Save the screenshot after a plan's first action: latch audit shot ID 1 --output step-1.png

This page is made from its source in latch-cli. Found a mistake? Open a pull request there.