Commands

Every Roost command, generated from Fruit Bat 0.48.0. In Roost, help <command> shows the same. In Roost Script each command is a function: wait-for "x" --gone is waitFor('x', { gone: true }).

Tabs

tabs

tabs [numbers…] [--site <site>] [--older <time>] [--dupes] [--group <name>] [--pinned] [--unpinned] [--playing] [--muted]

List open tabs (number, title, site)

Tab numbers count from the left (or the top in vertical tabs).
--older 3d: tabs you haven’t looked at for that long (12h, 3d, 2w). --dupes: the extra copies of pages open more than once.
--group picks a tab group by name. Filters can be combined.

Examples

tabs
tabs --site youtube.com
tabs --older 3d --unpinned | close
tabs --dupes | close
tabs --group Research | session save research

go

go <number>

Switch to a tab

Examples

go 3
tabs | grep inbox | go

close

close [numbers…] [--site <site>]

Close tabs (asks first if it’s more than 3)

Examples

close 4
tabs --site youtube.com | close

pin [numbers…]

Pin tabs

unpin

unpin [numbers…]

Unpin tabs

mute

mute [numbers…]

Mute tabs

Examples

tabs --playing | mute

unmute

unmute [numbers…]

Unmute tabs

reload

reload [numbers…]

Reload tabs

group

group "<name>" [--color <color>] [--new]

Put tabs in a tab group (joins one with that name)

Colors: grey, blue, red, yellow, green, pink, purple, cyan, orange.
If a group with that name exists, the tabs join it; --new makes a separate one.

Examples

tabs 3 7 11 | group "Bat research" --color green
tabs --site github.com | group GitHub

new

Open a new tab

ungroup

ungroup [numbers…]

Take tabs out of their groups

collapse

collapse "<group>"

Fold a tab group away

expand

expand "<group>"

Open a folded tab group

move

move --start | --end | --to <number>

Move tabs (the current one, or those piped in)

Examples

tabs --site github.com | move --start
move --to 3

Pages

open

open <site or search…> [--here]

Open sites or a search in new tabs (--here: in this tab)

With links, history or bookmarks piped in, opens each one (asks first past 5).
Several sites in a row open one tab each.
Followed by |, the new tabs go along: open a.example b.example | group Work

Examples

open github.com
open "fruit bat diet"
history --since yesterday | grep recipe | open
open mail.example cal.example | group Morning

url

The current page’s address

page

page [--css <selector>]

The current page’s text, line by line (or just the parts --css picks)

Examples

page | grep -i price
page | wc
page | summarize
page --css ".price"
page --css "h2" | head 5

links

Every link on the current page

Examples

links | grep pdf
links | grep -i chapter | head 3 | open

find

find "<text>"

Find on the page

Examples

find "echolocation"

reader

Switch Reader view on or off

speak

speak [text…] [--page] [--stop]

Read text aloud with your computer’s voice

speak "hello" reads the words; page | speak reads what’s piped in; speak --page (or speak on its own) reads the selected text, else the page.
speak --stop stops. The voice and speed are in Settings › General › Read aloud. Ctrl+Shift+U does the same from anywhere.

Examples

speak "Your tabs are tidy"
speak
page --css "article" | speak
speak --stop

back

Go back on this tab

forward

Go forward on this tab

click

click "<text>" [--nth <n>]

Click a link or button on the page by its text

Matches the visible text (exact first, then partly). --nth 2 picks the second match.
Asks first for things like Buy, Pay, Delete, Send, Submit or Sign out. Waits for the page to load after.

Examples

click "Next page"
click "Accept all"
click "Reply" --nth 2

fill

fill "<field>" "<text>"

Type into a field on the page (found by its label)

Finds the field by its label, placeholder or name. Works for text boxes, lists (picks the option) and checkboxes (yes/no).
Never fills passwords, card numbers, security or one-time codes.

Examples

fill "Search" "fruit bats"
fill "Email" "me@example.com"
fill "Country" "Canada"

scroll

scroll top|bottom|up|down

Scroll the page

wait-for

wait-for "<text>" [--gone] [--timeout <time>]

Wait until the page shows some text, or until it’s gone (10s, up to 1m)

Examples

wait-for "results"
wait-for "Order confirmed" --timeout 30s
wait-for "Loading" --gone

press

press <key> [--times <n>]

Press a key on the page (Enter, Escape, Tab, arrows…)

Keys: enter, return, space, escape, esc, tab, shift+tab, backspace, delete, up, down, left, right, home, end, pageup, pagedown, ctrl+a.
Enter on a form asks first if the form’s button says something like Buy, Pay, Send or Delete.

Examples

fill "Search" "fruit bats"
  press enter
press escape
press down --times 3

type

type "<text>"

Type into whatever field has the cursor

Click or fill a field first. Never types into password, card or code fields. Up to 1000 characters.

Examples

click "Write a comment"
  type "Lovely bats!"

hover

hover "<text>"

Move the mouse over something (opens hover menus)

Examples

hover "Products"
  click "Laptops"

zoom

zoom in|out|reset|<percent>

Zoom this page

Examples

zoom 125
zoom reset

History and bookmarks

history

history [words…] [--since <when>] [-n <count>]

Pages you visited, newest first

--since takes today, yesterday, 12h, 3d or 2w. Shows 50 unless you pick -n.

Examples

history --since yesterday
history recipe -n 10
history --since 3d | grep -i bat | open

forget

forget <site>

Remove a site from history (asks first)

Examples

forget batwatch.example

bookmarks

bookmarks [folder]

List bookmarks (or one folder)

Examples

bookmarks
bookmarks Recipes
bookmarks | grep -i news | open

bookmark

bookmark [--to <folder>]

Bookmark the current tab, or what’s piped in

Examples

bookmark
tabs --site arxiv.org | bookmark --to Reading

Echo (AI on this computer)

ask

ask "<question>"

Ask Echo about what’s piped in (or this page)

Echo is the AI on this computer; nothing is sent anywhere.

Examples

page | ask "what are the three main points?"
tabs | ask "which of these are about travel?"
ask "what does this page say about prices?"

summarize

Summarize what’s piped in (or this page)

Examples

summarize
page | grep -i review | summarize

translate

translate [--to <language>]

Translate what’s piped in (or this page)

Examples

translate --to spanish
page | head 5 | translate --to french

Chat (Chirp)

chirp

Chat on IRC with Chirp

chirp (or chirp list) shows your chats; chirp unread only those with new messages.
chirp read #rust shows the latest messages (-n 20 for more or fewer, up to 200).
chirp say #rust "text" sends a message; chirp share #rust sends this page’s title and link.
chirp join #rust, chirp part #rust, and chirp open [#rust] to show Chirp’s panel.
--net libera picks the network when you’re on more than one.
Chirp is off until you turn it on (in setup, or Add-ons › Chirp).
Roost sends at most 5 messages a minute. Echo’s scripts ask you before every message.

Examples

chirp unread
chirp read #fruitbat -n 10 | grep -i release
chirp say #fruitbat "back in 10"
chirp share #fruitbat
chirp read #rust | ask "what did I miss?"

Wallet (Web3)

wallet

Fruit Bat Wallet (Web3)

wallet balance shows your coins on this network; wallet address prints your address (| copy copies it).
wallet accounts, wallet networks, wallet network base (switch), wallet activity (| open shows them on the explorer).
wallet sites lists connected sites; wallet disconnect app.example disconnects one.
wallet send 0.01 ETH to 0x… prepares a payment. Nothing is sent until you press Approve in the wallet panel.
wallet send only works when you type it, never from scripts, jobs or Echo.
The wallet must be on (Settings › Wallet). It’s never available in Vampire Bat windows.

Examples

wallet
wallet balance
wallet address | copy
wallet activity -n 5 | open
wallet network base
wallet send 0.005 ETH to 0x1234…

Downloads, torrents and Lime Blocker

downloads

downloads [--done]

Recent downloads

get

get <address>

Download a file (asks first)

Examples

get https://example.com/file.zip

blocked

What Lime Blocker caught today

lime

lime on|off

Turn Lime Blocker on or off everywhere

notify

notify "<text>"

Show a note in the window (and a system notification)

Examples

notify "Tickets are on sale!"

torrent

Torrents with Colony

torrent lists your torrents (with numbers); torrent add magnet:?… adds one (or pipe links in: links | grep magnet | torrent add).
torrent pause 2, torrent resume 2, torrent pause all; a torrent is its number, part of its name, or the start of its hash.
torrent remove 2 asks first and keeps the files; add --files to delete them too.
torrent files 2, torrent stats, torrent open 2 (shows it in Colony).
Colony has to be on (Settings › General). Never in private or Vampire Bat windows: peers see your IP address.

Examples

torrent
torrent add magnet:?xt=urn:btih:…
links | grep -i magnet | torrent add
torrent pause all
torrent files 1
torrent remove 2

Your commands (aliases and scripts)

alias

alias [name [= command…]]

Make a short name for a command line

alias on its own lists them; alias name shows one. Extra words after an alias go on the end.
unalias name removes one.

Examples

alias bats = tabs | grep -i bat
bats | group "Bats"
alias yt = tabs --site youtube.com
yt | mute

unalias

unalias <name>

Remove an alias

script

Saved scripts: several lines, run by name

A script is a few Roost lines saved under a name. Type its name (or run name) to run it.
It can run when Fruit Bat opens, or from a shortcut (Ctrl+Alt+a letter; ⌘⌥ on Mac). Set those in the editor.
Lines run in order and stop at the first that fails. Commands that normally ask first need --yes in a script.
# starts a comment; end a line with \ to continue it on the next.
Words after a script’s name go to it: tidy youtube.com gives $1 (Roost Basic) or args[0] (Roost Script). remember and recall keep values between runs.
script pin <name> puts it on the toolbar’s ▶ Scripts button. Your scripts are also in the right-click menu.
script export <name> saves one as a .roost file. Double-clicking a .roost file, dropping it on Fruit Bat, or script open shows it in Roost, checked with the rules for outside scripts, and asks before it runs.
script new <name> --js starts one in Roost Script, the JavaScript-style language (help roost-script). The editor can switch a script between the two.

Examples

script new morning
script new tidy --js
script ls
morning
script export morning
script open
script rm morning

remember

remember <name> <value> | remember <name> --rm | remember --clear | remember

Keep a value for the next time a script runs

Each saved script has its own memory, and so does the prompt. recall("name") gives it back: in Roost Basic set old = recall("price", 0), in Roost Script const old = recall("price", 0). Numbers come back as numbers.
remember on its own lists what this script (or the prompt) remembers. --rm forgets one; --clear forgets them all.
Up to 50 values per script, 2000 characters each. Kept with your settings; deleting a script forgets its memory. Not in private or Vampire Bat windows.

Examples

remember price 18.99
remember last-run "${today()}"
remember
remember price --rm

recall

recall <name> [--or <default>]

Show a value a script remembered (in scripts, use recall("name"))

At the prompt this reads the prompt’s memory. In a script, recall reads that script’s own memory.

Examples

recall price
recall price --or 0

run

run <script> [words…] [--step]

Run a saved script (or just type its name)

Words after the name go to the script: in Roost Basic as $1, $2 … $9 and $args (all of them); in Roost Script as args[0], args[1] ….
--step runs one command at a time: Roost shows the next one and asks y (run it), n (stop) or a (run the rest).

Examples

run morning
run tidy --step
tidy youtube.com
run watch-price "https://shop.example/item" 50

Sessions

session

session ls | save <name> [--close] | open <name> | rm <name>

Save this window’s tabs and bring them back later

Groups and pinned tabs come back too. --close closes the tabs after saving (asks first).
Sessions are saved from normal windows only.

Examples

session save research --close
session ls
session open research

Automation

every

every <time> <command…>

Run a command again and again (at most once a minute)

Times: 30s, 10m, 2h, 1d. Jobs run in this window until you kill them or close it.
Commands that ask first need --yes here.

Examples

every 15m reload 3
every 1h tabs --dupes | close --yes
every 30m blocked

after

after <time> <command…>

Run a command once, later

Examples

after 25m open calendar.example
after 1h tabs --site youtube.com | close --yes

watch

watch [tab number] [--css <selector>] [--every <time>] [--reload]

Tell me when part of a page changes

--css picks the part to watch (like ".price"); without it the whole page text is watched.
--reload reloads the page before each check, for pages that don’t update by themselves. Checks every 5m unless you say.
A change shows here, as a note in the window and (in normal windows) as a system notification.

Examples

watch --css ".price" --every 10m --reload
watch 3 --css "#status"
jobs
kill 2

Examples

links | grep pdf | copy
tabs | copy --csv
url | copy

save

save [file name] [--csv | --json]

Save what’s piped in to a file in Downloads (asks first)

This is the only command that writes a file. It goes in your Downloads folder, never anywhere else.

Examples

tabs | save my-tabs --csv
page | save article
history --since today | save --json

json

Show what’s piped in as JSON

Examples

tabs | json
links | head 3 | json

Working with lists

echo

echo <text…>

Print text (or pass it along)

Examples

echo hello
echo github.com | open

grep

grep [-i] [-v] <words>

Keep lines that contain the words

-i ignores upper/lower case, -v keeps lines that don’t match. Words in quotes are matched together.

Examples

tabs | grep -i bat
links | grep -v facebook

sha256 unless you pick another. Handy for checking text against a published checksum, or spotting when part of a page changed.
Piped lines are hashed together (joined by new lines); --each gives one hash per line.
md5 and sha1 are fine for checksums but not for anything secret.
In scripts: md5(text), sha256(text) or hash(text, "sha512").

Examples

hash "hello"
hash hello --md5
page --css "#terms" | hash
tabs | hash --each

Roost has two languages. Roost Basic is the shell style (tabs --site x | close). Roost Script looks like JavaScript.
Commands are functions: tabs({ site: "x" }) runs tabs --site x and gives back the tabs. A list goes in first: close(tabs({ dupes: true })).
Lists can be piped with a dot: links().grep(/pdf/i).head(3).open(). Commands with actions: chirp.say("#rust", "hi"), wallet.balance().
At the prompt, let and const stay for the next js line. A saved script is Roost Script when its first line is // roost script.
Same limits and safety as Roost Basic: Ctrl+C stops it, big changes ask first, and there’s no eval, files or network.
help roost-script lists everything it can do.

Examples

js tabs().length
js tabs().filter(t => t.site === "youtube.com").map(t => t.title)
js for (const t of tabs({ dupes: true })) print(t.title)

Examples

help
help tabs
help grep