Fruit Bat Docs

Roost

A command line and scripting language for your browser.

A command line for Fruit Bat along the bottom of the window: the >_ Roost toolbar button, menu › Roost, or Ctrl+**. Type **help** to list the commands, or **help ` for one, with examples.

  • Pipes: | passes tabs, links or text from one command to the next. tabs | grep -i bat | group "Bat research" --color green links | grep pdf | head 3 | open page | ask "what are the three main points?" history --since yesterday | grep -i recipe | open tabs --site youtube.com | close
  • Commands:
    • Tabs: tabs, go, close, pin, unpin, mute, unmute, reload, group, new.
    • Pages: open [--here], back, forward, url, page [--css SELECTOR], links, find, reader, zoom.
    • Acting on a page: click "text", fill "field" "text", press enter|escape|tab|…, type "text", hover "text", scroll top|bottom|up|down, wait-for "text" [--gone].
    • Groups and order: group (joins a group of that name if there is one; --new for a fresh one), ungroup, collapse, expand, move --start|--end|--to N.
    • Library: history, forget, bookmarks, bookmark.
    • Echo: ask, summarize, translate.
    • Chat (Chirp): chirp, chirp unread, chirp read #channel [-n 20], chirp say #channel "text", chirp share #channel, chirp join, chirp part, chirp open, with --net NAME when you're on several networks. At most 5 messages a minute.
    • Torrents (Colony): torrent (or colony), torrent add LINK (or pipe links in), torrent pause|resume N|all, torrent remove N [--files] (asks first), torrent files N, torrent stats, torrent open [N]. Colony has to be on (Settings › General).
    • Wallet (Web3): wallet, wallet balance, wallet address, wallet accounts, wallet networks, wallet network NAME, wallet activity, wallet sites, wallet disconnect SITE, wallet lock, wallet open.
      • wallet send 0.01 ETH to 0x… only prepares a payment; nothing is sent until you press Approve in the wallet panel. It works only when you type it (never from scripts, jobs or Echo).
      • The wallet has to be on (Settings › Wallet). It's never available in Vampire Bat windows.
    • Other: downloads, get, blocked, lime, notify.
    • Lists: grep [-i] [-v], sort [-r], head, tail, uniq, wc, echo.
    • Aliases: ls (tabs), cd (go), man (help).
  • Tab numbers count from the left (or the top with vertical tabs), as tabs shows them.
  • Keys: Tab completes, ↑/↓ for earlier lines, Ctrl+R searches them, Ctrl+C stops or answers no, Ctrl+L clears, Esc clears the line.
  • Safety:
    • Roost only does what you could do by hand in the browser; it can't touch your files or run programs.
    • It asks before closing more than 3 tabs, opening more than 5, forgetting a site or downloading.
    • Commands that change something must come last in a line, and a line with a mistake anywhere doesn't run at all.
    • Text from websites (tab titles, page text, links) is shown only as text and goes to Echo marked as untrusted.
    • click, fill, scroll and wait-for work only on web pages, never on Fruit Bat's own pages.
    • click asks first when the button sounds risky (buy, pay, delete, send, submit, sign out and similar).
    • fill, type and value() refuse password, card, one-time-code and other secret fields.
    • press enter asks first when the form's button sounds risky.
  • Private and Vampire Bat windows: Roost sees only that window and keeps typed commands in memory only. Vampire Bat's Roost can't see history or bookmarks.
  • Not yet: the system terminal (a real bash/PowerShell tab), torrents, cookies, the developer commands (request, headers, storage) and moving tabs between windows from Roost.

Scripting: two languages#

Roost has two scripting languages. They share the same commands, limits and safety rules.

  • Roost Basic is the command-line style below (help scripting). It's the default.
  • Roost Script looks like JavaScript (help roost-script). See the next section.

Roost Basic#

Saved scripts are a small language on top of Roost commands; help scripting explains it.

# tidy: close YouTube in the evening, pin the bat tabs
set yt = $(tabs --site youtube.com)
if count($yt) > 0 and hour() >= 18
  echo "Closing $yt.count YouTube tabs"
  $yt | close --yes
end
for tab in $(tabs --unpinned)
  if $tab.title contains "bat"
    $tab | pin
  end
end
  • Statements: set, print, if/else if/else/end, for … in … end, repeat N … end, while … end, try … catch [name] … end, break, continue, stop, fail, wait, vars, unset.
  • try/catch: a failed line inside try jumps to catch with the reason in $error. Ctrl+C, answering no, and the runaway limits can't be caught.
  • Browser functions: title(), url() and tabcount() read the current tab and window.
  • Page checks: has("text"), exists("button text"), read("css"), readall("css"), value("field"), for example if exists("Accept all").
  • Editor: script new NAME opens it. It's coloured, has line numbers, and marks the line with a mistake as you type.
    • Ctrl+S saves, Ctrl+Enter runs the lines without saving, Ctrl+Shift+Enter (Step) asks before each command, and Ctrl+E goes back to it.
    • run NAME --step steps through a saved script.
  • Values: numbers, "text" (with $var inside), 'literal text', [lists], $(command output) and $var.field. Tabs have .title, .url, .site, .number, .pinned and more.
  • Safety: values put into commands are always quoted. Loops stop at 1000 rounds, a run stops at 20,000 steps, and wait is capped at a minute. Ctrl+C stops a script.

Roost Script (JavaScript style)#

A script is Roost Script when its first line is // roost script. script new NAME --js starts one, and the editor's language menu switches a script between the two (it changes the first line, not your code). At the prompt, js … runs one line.

// roost script
// tidy: close YouTube in the evening, pin the bat tabs
const yt = tabs({ site: 'youtube.com' })
if (yt.length > 0 && hour() >= 18) {
  print(`Closing ${yt.length} YouTube tabs`)
  close(yt, { yes: true })
}
for (const tab of tabs({ unpinned: true })) {
  if (tab.title.toLowerCase().includes('bat')) pin(tab)
}
  • Commands are functions. tabs({ site: 'x' }) runs tabs --site x and returns the tabs. Options go in a last { }; true gives a flag. Dashes become capitals: waitFor('Sign in').
  • Lists go in as arguments (close(list)), or pipe with a dot: links().grep(/pdf/i).head(3).open().
  • Commands with actions: chirp.say('#rust', 'hi'), wallet.balance(), torrent.pause(2).
  • Output: a command on its own line shows its output, like Roost Basic. Used as a value it's quiet and returns its result (items, or text).
  • The language:
    • let/const, if/else, for…of, for (;;), while, do…while, switch, break, continue;
    • functions and arrows (closures), default and rest parameters, destructuring and ...spread;
    • try/catch/finally and throw new Error('…');
    • templates, /regex/ (simple patterns only), ?., ??, typeof.
  • Built in: print, console.log, wait('2s'), fail, stop, range, Math, JSON, Object.keys/values/entries, text and list methods, plus Roost Basic's page checks and browser functions (has(), exists(), read(), readAll(), value(), title(), url(), tabCount()…).
  • Classes: fields, constructor, methods, static, extends, super, new, this, instanceof; classes can extend Error. No getters/setters or #private fields.
  • Not included: async/await (everything already waits), imports and eval. Scripts can't reach Node, the network or files, only Roost's commands.
  • Safety: the same limits as Roost Basic (1000 rounds per loop, 20,000 steps, 2,000-item lists), plus a 200-deep call limit. Ctrl+C, answering no and the limits can't be caught. Step (Ctrl+Shift+Enter) asks before each command.
  • Echo: Settings › General › Language for Echo's Roost scripts picks which one Echo writes. Every command a Roost Script card names is checked with Echo's rules on the card, and each command line is checked again as it's built while the script runs (so a command made up at run time can't slip through). { yes: true } is refused.

Script words, memory and the toolbar#

  • Words: tidy youtube.com gives the script $1 (Roost Basic) or args[0] (Roost Script). $args / args hold every word.
  • Memory: remember price 18.99 keeps a value for the next run; recall("price", 0) reads it back.
    • Each script has its own memory, and so does the prompt.
    • Stored under the roostMemory setting. Never written from private windows; off for Echo's scripts and .roost files.
  • Outside the panel: script pin NAME (or On the toolbar in the editor) adds the script to the toolbar's ▶ button, and the page's right-click menu has Run Roost script ›.

.roost files#

A Roost script (either language) can be saved as a .roost file to keep or share: script export NAME.

  • Opening one:
    • double-click it (Fruit Bat registers .roost files);
    • drop it on a page;
    • type or paste its path into the address bar;
    • script open;
    • open it from Downloads.
  • Nothing runs straight away. Roost shows the script, checked line by line, and asks: y runs it, e opens it in the editor, Enter cancels.
  • Outside-script rules: a file runs with Echo's rules, because a file can come from anyone.
    • Only Echo's commands. No --yes.
    • Roost Script commands are checked again as they're built.
    • At most 30 new tabs and 100 clicks per run; 500 lines per file.
    • Saving it from the editor makes it your own script, with every command.

Full reference#

Every command, function and example is in the Roost docs at docs.roostlang.org.