Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

ratclone

ratclone is a keyboard-driven terminal UI for rclone, with Vim keys. Browse your accounts and the local disk, copy and move between them, rename and delete, and keep transfers running in the background, even after you quit.

What it does

  • Browses every rclone account and the local disk, in one pane or two side by side.
  • Copies and moves files between any two places, with a question when a name is already taken: replace, skip or keep both, once or for all of them.
  • Runs every copy and move as an rclone job. Transfers keep going while you browse and, if you choose, after you quit or your SSH session drops.
  • Shows the equivalent rclone command for copies, moves and deletes.
  • Shows where an account’s space goes, with folders ranked by size, file types and the largest files.
  • Adds, edits and signs in to accounts, including browser logins over SSH.
  • Restyles live: eleven built-in themes, your own themes, Nerd Font or ASCII icons.

Where to start

  • Installation: packages for Debian, Ubuntu, Fedora, openSUSE and Arch, a static binary for any Linux, or cargo install.
  • Getting started: the first run, and --demo to look around without touching your accounts.
  • Key bindings: every key on one page.

ratclone is free software under the MIT licence. The source, issues and discussions are on GitHub.

Installation

ratclone runs on Linux, on x86_64 and aarch64. It needs:

  • rclone v1.68.0 or newer. ratclone checks the version when it starts and says so if it is older. Browser login inside the app needs v1.75.0 or newer; older supported versions use the authorization-token flow.
  • A terminal with truecolor and a Nerd Font for the icons. Without one, set icons = "ascii" in the configuration or in the settings (,).

Getting a recent rclone

Fedora, openSUSE Tumbleweed and Arch Linux ship a recent enough rclone, and the packages below install it for you. Debian and Ubuntu ship rclone 1.60, which is too old. Install the current release from rclone’s own site instead, which puts it in /usr/bin:

sudo -v ; curl https://rclone.org/install.sh | sudo bash

rclone’s install page has the other ways, including its own .deb and .rpm packages. Check with rclone version.

Packages

Each release has packages and archives on the releases page, with SHA256SUMS listing the checksum of every file. x86_64 files are named amd64 or x86_64, aarch64 files arm64 or aarch64. The binary inside is static (musl), so it does not depend on your distribution’s glibc.

SystemFileInstall
Arch LinuxAURparu -S ratclone-bin (or ratclone to build from source)
Arch Linuxratclone-VERSION-1-x86_64.pkg.tar.zstsudo pacman -U ./ratclone-*-x86_64.pkg.tar.zst
Debian, Ubunturatclone_VERSION-1_amd64.debsudo apt install ./ratclone_*_amd64.deb
Fedora, RHELratclone-VERSION-1.x86_64.rpmsudo dnf install ./ratclone-*.x86_64.rpm
openSUSEratclone-VERSION-1.x86_64.rpmsudo zypper install --allow-unsigned-rpm ./ratclone-*.x86_64.rpm
Any Linuxratclone-VERSION-x86_64-unknown-linux-musl.tar.gzunpack it and put ratclone on your PATH

The Arch and RPM packages depend on rclone and install it. The .deb only suggests it, because the rclone in Debian and Ubuntu is too old: install it as described above.

Check a download, and its build provenance (which proves it was built by this repository’s release workflow), with the GitHub CLI:

sha256sum --check --ignore-missing SHA256SUMS
gh attestation verify ratclone_*_amd64.deb --repo SyscallBrain/ratclone

From crates.io

With Rust 1.88 or newer:

cargo install --locked ratclone

From source

git clone https://github.com/SyscallBrain/ratclone
cd ratclone
cargo build --release
./target/release/ratclone

Try it first

ratclone --demo

Demo mode shows made-up accounts and files. Nothing touches rclone or your accounts, so it is safe to try every key.

Getting started

The first run

ratclone

ratclone starts its own rclone in the background and lists the accounts (rclone calls them remotes) from your rclone configuration, plus the local disk. If you have no accounts yet, press a in the accounts list to add one, or run rclone config first.

To look around without touching anything:

ratclone --demo

Moving around

The screen has an accounts list on the left and a file pane on the right. Tab moves between them.

  • j k move down and up, l or Enter opens, h or Backspace goes to the parent folder.
  • gg and G jump to the first and last entry, Ctrl-d Ctrl-u move half a page. Counts work: 5j.
  • / filters the folder as you type, n N cycle the matches.
  • - goes back to the previous folder.
  • ? shows every key.

A first copy

  1. Press | to open a second pane beside the first.
  2. In one pane, go to the files you want to copy and mark them with Space (or v for a visual selection).
  3. Press > (or F5) to copy them to the folder open in the other pane, or F6 to move them.

Or copy and paste: y copies the marked files, x cuts them, and p pastes them in the folder you are in.

The copy runs as an rclone job. Watch it in the info panel, or press T for the Transfers tab.

Quitting

q quits. If transfers are still running, ratclone asks whether to keep them running in the background, wait for them, or cancel them. Background transfers show up again the next time you open the app. The settings can make the choice for you.

The interface

Tabs

The top line shows the three tabs:

gt and gT go to the next and previous tab.

Accounts list

The left column lists the local disk and every rclone account, with how full each one is. Tab focuses it; j k and Enter open an account in the pane. From the pane, Ctrl-n and Ctrl-p switch to the next or previous account without leaving it. The accounts chapter covers adding and editing them.

On terminals narrower than 80 columns the accounts list is hidden, to leave room for the files.

File panes

The pane shows the folder you are in: its path on the top border, the number of items, and the marked count. sn ss sm sort by name, size or modification time, sr reverses the order, and . shows hidden files.

| opens a second pane beside the first, and closes it again. Tab and Shift-Tab move between the accounts list and the panes.

Folders you visited recently open at once with the rows seen last time, while a fresh listing is fetched (a spinner next to the item count). Until it arrives you can move around and filter, but not change anything. R refreshes the folder and the account’s usage.

Info panel

The panel at the bottom shows the selected account: storage used, trash and free space, a sparkline of transfer speed over the last minute, and details of the file under the cursor. i hides and shows it. Short terminals get a one-line version. With two panes open, it follows the focused pane, or stays hidden if you choose so in the settings.

Bottom line

The last line shows messages and the keys that make sense where you are. The key hints can be hidden in the settings.

Help

? opens every key, grouped by what it does. The key bindings chapter has the same list.

Pasting text

Text pasted into the terminal only ever goes into the text field being edited (a name, a filter, a token). Anywhere else it is ignored, so a stray paste can never be read as keys.

Copying, moving and deleting

Choosing files

  • Space marks or unmarks the file under the cursor.
  • v (or V) starts a visual selection: move with j k and every file in between is selected.
  • Esc clears the marks.

With nothing marked, operations act on the file under the cursor.

Copy and move

There are two ways, and both run as rclone jobs in the background.

To the other pane. With two panes open (|), > or F5 copies the marked files to the folder in the other pane, and F6 moves them.

Copy and paste. y copies the marked files, x cuts them; go to any folder, on any account, and p pastes them there.

Copies between two folders of the same account are done by the cloud provider where it can (a server-side copy), so nothing goes through your computer.

When a name is already taken

If a file or folder with the same name is already in the destination, ratclone asks what to do:

  • r replaces it (not possible when one is a file and the other a folder),
  • s skips this one,
  • n keeps both, and gives the new one a free name, shown in the question.

With several conflicts, a applies the same choice to all the remaining ones. Enter confirms, Esc cancels the paste. Inside folders, rclone itself skips identical files and overwrites the ones that differ.

Rename, new folder, delete

  • r or cw renames the file under the cursor.
  • o (or a) creates a new folder.
  • dd or D deletes the marked files, or the one under the cursor, after asking.

The rclone command

The delete question lists the rclone commands it will run, and the Transfers tab shows the command behind each copy and move, so you can learn them or repeat them in a script.

Transfers

Every copy and move is an rclone job. The Transfers tab (T, or Alt-3) lists them: running, finished, stopped and failed, with their speed and progress. Under the list, the selected transfer shows each file with its size and progress, and the rclone command behind it.

KeyAction
j k, gg Gmove
s or xstop the transfer
Enter or rresume a stopped or failed transfer
cclear the finished transfers
dd or Dremove one transfer from the list
Cclear everything but the running ones
T, q or Escback to the files

In the background

Transfers do not need the app. Quit with transfers running and ratclone asks:

  • b: quit and keep them running in the background,
  • w: wait for them to finish, then quit,
  • c: cancel them and quit.

Set On quit with transfers in the settings to make this choice once and for all.

Background transfers keep going when the terminal is closed or an SSH session drops. A small helper records how each one ends and stops rclone once they are done. Open the app again and they are still there, running or with how they ended. The history is kept in ~/.local/state/ratclone/transfers.json.

Bandwidth

The Bandwidth limit setting caps the speed of every transfer, in rclone’s syntax: 10M for 10 MiB/s, 750k, or 10M:1M for separate upload and download limits.

Space

The Space tab (U, or Alt-2) shows where an account’s space goes: folders ranked by size with bars, the file types inside the selected folder, and its largest files. It is read-only: nothing is changed from here.

Scanning

A scan never starts by itself: press Enter to scan the account. It lists folders a few at a time (4, or 2 on Mega, which limits requests); set Scan in parallel in the settings, or scan_concurrency in config.toml, to change it. Esc cancels and keeps what was found so far.

Results are cached in ~/.cache/ratclone/scans and shown at once the next time. R scans again.

Keys

KeyAction
j k, gg G, Ctrl-d Ctrl-umove
l or Enteropen the folder (on the account, start the scan)
h or -parent folder
ss sn scsort by size, name or file count
/filter
gfopen the folder in the Files tab
Rscan again
Esccancel the scan, or go back
qback to the files
Tabswitch to the accounts list

Accounts

ratclone uses the accounts (rclone remotes) in your rclone configuration, rclone.conf. Accounts added or edited from the app are written there, so rclone on the command line sees them too.

These keys work in the accounts list (Tab to focus it):

KeyAction
aadd an account
eedit the selected account
Asign in again (a new token)
dd or Dremove the account
r or Rrefresh its usage

Adding an account

a asks for a type: type to filter the list, then Enter. Give the account a name, and fill in its fields:

  • Tab shows the advanced fields,
  • F1 shows the full help of a field,
  • Ctrl-d puts a field back to rclone’s default,
  • Ctrl-o on a remote path picks one of your accounts or the local disk (for crypt, alias and union accounts).

Enter on the last field, or Ctrl-s, sends it. Then answer rclone’s own questions, such as the login.

Editing

e opens the form filled in. Passwords show as ••••• (unchanged) and are only sent if you type a new one. Only the fields you change are sent.

Browser logins

Google Drive, Dropbox, OneDrive and other accounts log in through a browser.

  • On your own computer with rclone 1.75 or newer, the browser opens and the app waits for you. Older versions cannot cancel this login reliably, so the app automatically offers the authorization-token flow below. You can run the displayed command in another terminal on the same computer.
  • Over SSH there is no browser, so the app shows the command to run on a machine that has one, such as rclone authorize "dropbox". y copies it (through OSC 52, so it works over SSH too), and you paste the result back.

L switches between the two ways if the guess was wrong, and Esc cancels. A cancelled new account is removed, so nothing half-made stays in rclone.conf. A goes through the login again when a token has expired.

Removing an account

dd or D removes the account from rclone’s configuration, after asking. The files in the account are not touched. Accounts built on it (crypt, alias, union) are listed in the question. Removing an account is refused while transfers use it.

Settings

, opens the settings over the app. Changes show at once: cycle the themes with ← → and watch the whole app restyle. Enter saves to ~/.config/ratclone/config.toml, and Esc puts everything back.

Saving keeps your comments and any other keys in the file. Values left at their default are removed, so the file only holds what you changed.

SettingValuesconfig.toml
ThemeTokyo Night (default) and the other built-ins, plus your own themes/*.tomltheme
Transparent backgroundtheme default · on · offtransparent
IconsNerd Font · ASCIIicons
Key hintsshown · hiddenkey_hints
Info panelshown · hiddeninfo_panel
Info panel with two panesfocused pane · hiddeninfo_panel_split
Start inlast location · home folder · an accountstart_in
Default sortname · size · modifiedsort
Hidden filesoff · onshow_hidden
On quit with transfersask · keep running · waiton_quit
Bandwidth limitoff · 1M · 5M · 10M · 50M · custombwlimit
Scan in parallelauto · 1 · 2 · 4 · 8 · 16scan_concurrency

The quick keys i (info panel), . (hidden files) and s… (sort) change only the current session. The configuration chapter describes every key of the file.

Key bindings

? shows these in the app. Counts work with movement: 5j.

KeysAction
j k (or ↓ ↑)down, up
h (or ←, Backspace)parent folder
l (or →, Enter)open
gg Gfirst, last entry
Ctrl-d Ctrl-uhalf page down, up
-previous folder
Tab Shift-Tabmove between the accounts list and the panes
Ctrl-n Ctrl-pnext, previous account, from the pane (Files and Space)
|open or close a second pane
/ then n Nfilter the folder, next and previous match
sn ss smsort by name, size, modified
srreverse the sort
.show or hide hidden files
Rrefresh the folder and its account’s usage
ishow or hide the info panel

Files

KeysAction
Spacemark
v Vvisual selection
Escclear the selection
ycopy
xcut
ppaste here
> or F5copy to the other pane
F6move to the other pane
r or cwrename
o or anew folder
dd or Ddelete (asks first)

Tabs

KeysAction
gt gTnext, previous tab
Alt-1 Alt-2 Alt-3Files, Space, Transfers
USpace
TTransfers

Accounts list

KeysAction
l or Enteropen the account
aadd an account
eedit the account
Asign in again
dd or Dremove the account
r or Rrefresh its usage

Transfers tab

KeysAction
s or xstop
Enter or rresume
cclear finished
dd or Dremove from the list
Cclear all but running
T, q or Escclose

Space tab

KeysAction
Enteropen the folder, or start the scan
l h (or -)into a folder, back out
ss sn scsort by size, name, file count
/filter
gfopen the folder in Files
Rscan again
Esccancel the scan, or go back
qback to the files

Everywhere

KeysAction
,settings
?help
q or Ctrl-cquit (asks what to do with running transfers)

Configuration

Settings live in ~/.config/ratclone/config.toml (or $XDG_CONFIG_HOME/ratclone/config.toml). The file is optional: every key has a default. The settings screen (,) writes it for you and keeps your comments.

theme = "tokyo-night"
transparent = false
icons = "nerd"
key_hints = true
info_panel = true
info_panel_split = "focused"
start_in = "last"
sort = "name"
show_hidden = false
on_quit = "ask"
bwlimit = "off"
scan_concurrency = 4
rclone_path = "/usr/bin/rclone"
KeyValuesDefault
themea built-in theme or the name of a file in themes/; see Themes"tokyo-night"
transparenttrue: use the terminal’s background; false: paint the theme’sfalse
icons"nerd" (needs a Nerd Font) or "ascii""nerd"
key_hintsshow the keys on the bottom linetrue
info_panelshow the info panel at start-uptrue
info_panel_splitwith two panes: "focused" (the focused pane’s selection) or "hidden""focused"
start_in"last" (where you were), "home" (the home folder) or an account name"last"
sort"name", "size" or "modified""name"
show_hiddenshow files whose name starts with .false
on_quitwith transfers running: "ask", "background" (keep them running) or "wait""ask"
bwlimitrclone’s bandwidth syntax: "10M", "750k", "10M:1M" (upload:download) or "off""off"
scan_concurrencyfolders listed at once by a Space scan, 1 to 164, or 2 on Mega
rclone_paththe rclone binary to runrclone on your PATH

An unknown key or a wrong value is reported when ratclone starts, naming the problem, rather than ignored.

The --rclone option overrides rclone_path for one run.

Themes

ratclone has eleven built-in themes:

  • tokyo-night (default), tokyo-night-storm, tokyo-night-moon, tokyo-night-day
  • catppuccin-mocha, catppuccin-latte
  • gruvbox-dark, nord, dracula, kanagawa, everforest

The quickest way to choose is the settings screen (,): ← → on Theme restyles the whole app as you go, Enter keeps it and Esc puts the old one back. Or set theme in the configuration.

Your own theme

A custom theme is a file in ~/.config/ratclone/themes/, named after the theme: ~/.config/ratclone/themes/mytheme.toml is the theme mytheme. It shows up in the settings next to the built-in ones.

The file has a [tokens] table with sixteen colours, all of them required, as "#rrggbb":

[tokens]
bg      = "#1a1b26"  # background
bg2     = "#16161e"  # dialogs
hl      = "#292e42"  # highlights, the cursor in an unfocused pane
sel     = "#283457"  # the cursor row
gutter  = "#3b4261"  # dim lines
comment = "#565f89"  # secondary text
fg      = "#c0caf5"  # text
fg2     = "#a9b1d6"  # softer text
blue    = "#7aa2f7"
cyan    = "#7dcfff"
magenta = "#bb9af7"
green   = "#9ece6a"
yellow  = "#e0af68"
orange  = "#ff9e64"
red     = "#f7768e"
teal    = "#73daca"

A missing key or a malformed colour is reported with the key’s name.

Transparency

transparent = true leaves the background to your terminal, for a terminal with its own background image or opacity. false always paints the theme’s background, which is also what happens without the key.

Command-line options

ratclone [OPTIONS]
OptionDescription
--demoRun with made-up accounts and files; nothing touches rclone.
--rclone PATHThe rclone binary to run. Default: rclone_path in the configuration, or rclone on your PATH.
--socket PATHThe unix socket for ratclone’s own rclone rcd. Default: $XDG_RUNTIME_DIR/ratclone/rc.sock, or /tmp/ratclone-UID/rc.sock without XDG_RUNTIME_DIR.
-h, --helpPrint the options.
-V, --versionPrint the version.

Files and paths

ratclone follows the XDG base directories: each path below moves with XDG_CONFIG_HOME, XDG_STATE_HOME, XDG_CACHE_HOME or XDG_RUNTIME_DIR when it is set.

PathWhat
~/.config/ratclone/config.tomlsettings
~/.config/ratclone/themes/custom themes
~/.local/state/ratclone/transfers.jsontransfer history
~/.local/state/ratclone/ui.jsonwhere the Files tab was when you last quit
~/.local/state/ratclone/rcd.logthe log of ratclone’s rclone, rotated at 10 MiB
~/.local/state/ratclone/lists/file lists for multi-file pastes
~/.cache/ratclone/scans/Space scans
$XDG_RUNTIME_DIR/ratclone/rc.sockthe socket ratclone and its rclone talk through

Your accounts stay in rclone’s own configuration file, usually ~/.config/rclone/rclone.conf; rclone config file prints where it is. ratclone does not keep a copy of them.

How it works

Its own rclone

ratclone starts its own rclone rcd, rclone’s remote-control server, on a private unix socket ($XDG_RUNTIME_DIR/ratclone/rc.sock, in a directory only you can open) and talks to it through the rc API, which is only available through that socket. Browser logins may temporarily open a localhost port for OAuth. ratclone never builds shell commands.

Listing, renaming, deleting and account changes are rc calls. Copies and moves are rclone jobs, so they keep going while you browse.

Transfers outlive the app

Because transfers are jobs of the background rclone, they do not depend on the app. When you quit with transfers running, you choose to keep them running, wait, or cancel them (or set On quit with transfers once in the settings). If the terminal is closed or an SSH session drops, the app leaves and the transfers carry on.

When transfers are left running, a small helper (ratclone itself, started with a hidden option) watches them, records how each one ends in the transfer history, and stops the rclone once they are done. Open the app again and they are all there, running or with how they ended.

One at a time

Only one ratclone runs at a time, since it owns the rclone and the transfer history. Starting a second one while the first is open says so.

Listings

Folders you visited recently open at once with the rows seen last time, while a fresh listing is fetched; a spinner next to the item count shows it is on its way. Until it arrives you can move around and filter, but not change anything, so you never act on a stale list.

Demo mode

--demo replaces rclone with made-up accounts and files held in memory. Nothing is started and nothing is written to your accounts, which is why the screenshots and the presentation come from it.

Troubleshooting

“rclone not found”

ratclone runs rclone from your PATH. Install it (see Installation), or point ratclone at it with rclone_path in the configuration or --rclone PATH.

“rclone … is too old”

ratclone needs rclone v1.68.0 or newer, and Debian and Ubuntu ship 1.60. Install the current release from rclone.org:

sudo -v ; curl https://rclone.org/install.sh | sudo bash

If you have several rclones, rclone_path chooses which one ratclone runs.

“rclone rcd did not start” or “cannot reach rclone”

The background rclone failed to start or stopped answering. Its log is in ~/.local/state/ratclone/rcd.log; the last lines usually say why. A stale socket from a crash is cleaned up on the next start. If XDG_RUNTIME_DIR is not set (some su and container sessions), the socket goes to /tmp/ratclone-UID/ instead.

A copy or a listing fails

The error in the app is rclone’s own. Try the same thing with the rclone command shown for the transfer, and check rcd.log. Expired logins are a common cause: A in the accounts list signs in again.

Icons show as boxes or question marks

The icons need a Nerd Font in your terminal. Install one, or switch to ASCII icons: Icons in the settings (,), or icons = "ascii" in config.toml.

No colours, or wrong colours

ratclone draws in truecolor. Most terminals support it; inside tmux, add set -as terminal-features ",*:RGB" to ~/.tmux.conf. When the NO_COLOR environment variable is set, colours are turned off.

“Window too small”

The terminal is too small to draw the app: make it bigger. Below 80 columns the accounts list is hidden to leave room for the files.

The browser does not open for a login

Over SSH there is no browser, so ratclone shows an rclone authorize command to run on a machine that has one. If it guessed wrong, L switches between the two ways. See Browser logins.

Still stuck?

Ask in Discussions, or open an issue with your ratclone and rclone versions and the last lines of rcd.log.

Contributing

Bug reports, ideas and pull requests are welcome. Questions go to Discussions; security problems to a private report. CONTRIBUTING.md has the full guide.

Building and testing

git clone https://github.com/SyscallBrain/ratclone
cd ratclone
cargo run -- --demo
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test

The tests that talk to a real rclone rcd skip themselves when rclone is not installed. UI changes update the insta snapshots in tests/snapshots/; review them with cargo insta review.

This guide

The guide is an mdBook in book/. Preview it with:

mdbook serve book --open

Project layout

PathWhat
src/app/the application state and what each key does
src/ui/drawing, one module per part of the screen
src/input/key parsing and the key map
src/backend/the rclone backend (rc.rs) and the demo one (fake.rs)
src/rc/the rc API client over the unix socket
src/daemon.rs, src/reaper.rsstarting rclone, and stopping it when background transfers end
src/transfer/transfer specs and the history
src/scan/the Space scans
src/theme/built-in and custom themes
tests/integration and snapshot tests