Introduction
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
rclonecommand 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
--demoto 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.
| System | File | Install |
|---|---|---|
| Arch Linux | AUR | paru -S ratclone-bin (or ratclone to build from source) |
| Arch Linux | ratclone-VERSION-1-x86_64.pkg.tar.zst | sudo pacman -U ./ratclone-*-x86_64.pkg.tar.zst |
| Debian, Ubuntu | ratclone_VERSION-1_amd64.deb | sudo apt install ./ratclone_*_amd64.deb |
| Fedora, RHEL | ratclone-VERSION-1.x86_64.rpm | sudo dnf install ./ratclone-*.x86_64.rpm |
| openSUSE | ratclone-VERSION-1.x86_64.rpm | sudo zypper install --allow-unsigned-rpm ./ratclone-*.x86_64.rpm |
| Any Linux | ratclone-VERSION-x86_64-unknown-linux-musl.tar.gz | unpack 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.
jkmove down and up,lorEnteropens,horBackspacegoes to the parent folder.ggandGjump to the first and last entry,Ctrl-dCtrl-umove half a page. Counts work:5j./filters the folder as you type,nNcycle the matches.-goes back to the previous folder.?shows every key.
A first copy
- Press
|to open a second pane beside the first. - In one pane, go to the files you want to copy and mark them with
Space(orvfor a visual selection). - Press
>(orF5) to copy them to the folder open in the other pane, orF6to 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:
- Files (
Alt-1): the accounts list and one or two file panes. - Space (
Alt-2, orU): where an account’s space goes. - Transfers (
Alt-3, orT): running and finished transfers.
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
Spacemarks or unmarks the file under the cursor.v(orV) starts a visual selection: move withjkand every file in between is selected.Escclears 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:
rreplaces it (not possible when one is a file and the other a folder),sskips this one,nkeeps 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
rorcwrenames the file under the cursor.o(ora) creates a new folder.ddorDdeletes 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.
| Key | Action |
|---|---|
j k, gg G | move |
s or x | stop the transfer |
Enter or r | resume a stopped or failed transfer |
c | clear the finished transfers |
dd or D | remove one transfer from the list |
C | clear everything but the running ones |
T, q or Esc | back 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
| Key | Action |
|---|---|
j k, gg G, Ctrl-d Ctrl-u | move |
l or Enter | open the folder (on the account, start the scan) |
h or - | parent folder |
ss sn sc | sort by size, name or file count |
/ | filter |
gf | open the folder in the Files tab |
R | scan again |
Esc | cancel the scan, or go back |
q | back to the files |
Tab | switch 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):
| Key | Action |
|---|---|
a | add an account |
e | edit the selected account |
A | sign in again (a new token) |
dd or D | remove the account |
r or R | refresh 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:
Tabshows the advanced fields,F1shows the full help of a field,Ctrl-dputs a field back to rclone’s default,Ctrl-oon 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".ycopies 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.
| Setting | Values | config.toml |
|---|---|---|
| Theme | Tokyo Night (default) and the other built-ins, plus your own themes/*.toml | theme |
| Transparent background | theme default · on · off | transparent |
| Icons | Nerd Font · ASCII | icons |
| Key hints | shown · hidden | key_hints |
| Info panel | shown · hidden | info_panel |
| Info panel with two panes | focused pane · hidden | info_panel_split |
| Start in | last location · home folder · an account | start_in |
| Default sort | name · size · modified | sort |
| Hidden files | off · on | show_hidden |
| On quit with transfers | ask · keep running · wait | on_quit |
| Bandwidth limit | off · 1M · 5M · 10M · 50M · custom | bwlimit |
| Scan in parallel | auto · 1 · 2 · 4 · 8 · 16 | scan_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.
Navigation
| Keys | Action |
|---|---|
j k (or ↓ ↑) | down, up |
h (or ←, Backspace) | parent folder |
l (or →, Enter) | open |
gg G | first, last entry |
Ctrl-d Ctrl-u | half page down, up |
- | previous folder |
Tab Shift-Tab | move between the accounts list and the panes |
Ctrl-n Ctrl-p | next, previous account, from the pane (Files and Space) |
| | open or close a second pane |
/ then n N | filter the folder, next and previous match |
sn ss sm | sort by name, size, modified |
sr | reverse the sort |
. | show or hide hidden files |
R | refresh the folder and its account’s usage |
i | show or hide the info panel |
Files
| Keys | Action |
|---|---|
Space | mark |
v V | visual selection |
Esc | clear the selection |
y | copy |
x | cut |
p | paste here |
> or F5 | copy to the other pane |
F6 | move to the other pane |
r or cw | rename |
o or a | new folder |
dd or D | delete (asks first) |
Tabs
| Keys | Action |
|---|---|
gt gT | next, previous tab |
Alt-1 Alt-2 Alt-3 | Files, Space, Transfers |
U | Space |
T | Transfers |
Accounts list
| Keys | Action |
|---|---|
l or Enter | open the account |
a | add an account |
e | edit the account |
A | sign in again |
dd or D | remove the account |
r or R | refresh its usage |
Transfers tab
| Keys | Action |
|---|---|
s or x | stop |
Enter or r | resume |
c | clear finished |
dd or D | remove from the list |
C | clear all but running |
T, q or Esc | close |
Space tab
| Keys | Action |
|---|---|
Enter | open the folder, or start the scan |
l h (or -) | into a folder, back out |
ss sn sc | sort by size, name, file count |
/ | filter |
gf | open the folder in Files |
R | scan again |
Esc | cancel the scan, or go back |
q | back to the files |
Everywhere
| Keys | Action |
|---|---|
, | settings |
? | help |
q or Ctrl-c | quit (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"
| Key | Values | Default |
|---|---|---|
theme | a built-in theme or the name of a file in themes/; see Themes | "tokyo-night" |
transparent | true: use the terminal’s background; false: paint the theme’s | false |
icons | "nerd" (needs a Nerd Font) or "ascii" | "nerd" |
key_hints | show the keys on the bottom line | true |
info_panel | show the info panel at start-up | true |
info_panel_split | with 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_hidden | show files whose name starts with . | false |
on_quit | with transfers running: "ask", "background" (keep them running) or "wait" | "ask" |
bwlimit | rclone’s bandwidth syntax: "10M", "750k", "10M:1M" (upload:download) or "off" | "off" |
scan_concurrency | folders listed at once by a Space scan, 1 to 16 | 4, or 2 on Mega |
rclone_path | the rclone binary to run | rclone 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-daycatppuccin-mocha,catppuccin-lattegruvbox-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]
| Option | Description |
|---|---|
--demo | Run with made-up accounts and files; nothing touches rclone. |
--rclone PATH | The rclone binary to run. Default: rclone_path in the configuration, or rclone on your PATH. |
--socket PATH | The 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, --help | Print the options. |
-V, --version | Print 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.
| Path | What |
|---|---|
~/.config/ratclone/config.toml | settings |
~/.config/ratclone/themes/ | custom themes |
~/.local/state/ratclone/transfers.json | transfer history |
~/.local/state/ratclone/ui.json | where the Files tab was when you last quit |
~/.local/state/ratclone/rcd.log | the 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.sock | the 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
| Path | What |
|---|---|
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.rs | starting 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 |