Your terminal tools, in one bag.
tote is a terminal launcher for SSH connections, Git repositories, shell aliases and shell functions, with a full-screen interface built on Bubble Tea. It is the Go successor of mn.
Status: version 1.1.0. Version 1.0.0 was the first release. What comes later is marked as planned.
You keep four kinds of records, each in a plain TOML file:
| Kind | What Enter does in the interface |
|---|---|
| Connections | Opens an ssh session, optionally through a via command such as a jump host. |
| Repositories | Changes the directory of your shell to the repository. |
| Aliases | Puts the command on your prompt, ready to run. |
| Functions | Puts the function name on your prompt, ready to run. |
The same records are available as commands (tote co, tote repos, ...), as real shell aliases and
functions loaded by tote init, and through a palette that searches all of them at once.
How it differs from mn:
- One static Go binary instead of a Bash program. Linux and macOS (amd64 and arm64) are the targets.
- Data in TOML files with a schema, written atomically, instead of
:::separated lines. - A new interface: lists with a detail panel, a palette, settings, mouse, themes, English and French.
- Plugins are rewritten, not ported. In tote 1.x they are declarative only (a manifest, no code of their own) and nothing runs before you have read the exact commands and agreed.
- There is no migration inside the program: a separate script moves your data from mn, see Moving your data from mn.
tote with no argument, run in a terminal, opens the full-screen interface; in a pipe or a script
it prints the help. tote co and tote config with no argument open it on the Connections list and
on the settings.
The welcome page is a boxed greeting with the number of records of each kind and a menu:
Connections, Repos, Aliases, Functions, Plugins, Settings. A list shows one kind in columns that
disappear from the right as the terminal narrows, with a filter line and a panel with the exact
command Enter would run (or the path of a repository and its Git branch). The palette searches every
record and a few actions from anywhere; the settings are changed in place and saved at once; the
Plugins screen lists installed and bundled plugins with their state; ? lists every key that
applies. The palette and the lists of choices grow with a wide or tall terminal, up to about 60% of
it, so that long names and commands are cut less often.
| Key | Where | Action |
|---|---|---|
1 to 4, and 5 when the plugins are on |
Welcome | Open the kind or Plugins, in menu order. Settings has no digit: use ,. |
Up, Down, k, j |
Everywhere | Move. h and l (or Left and Right) switch kind on a list. |
| Enter | Lists | Use the record: connect, go to the repository, put the command on the prompt. |
/ |
Lists | Filter: names and aliases that start with the text come first. Enter applies it and leaves the typing; on Connections the cursor lands on the row whose name or alias is exactly the text, and a second Enter uses the record. Esc clears it. |
n, e, d, v, C |
Lists | New, edit, delete (asks first), details, copy. On the Plugins screen d removes. |
v |
Settings | The whole description, values and note of the selected setting: the panel under the rows cuts long text. |
u, U, c |
Connections | Next login user, choose a user, put the ssh command on the prompt. |
o |
Repos | Open the repository in your editor. |
| Tab | Repos, Plugins | Menu of actions for the row (Repos: the actions that plugins add). |
Ctrl+K |
Everywhere | Palette. Prefixes narrow it: c connections, r repositories, a aliases, d functions, > actions. |
, |
Everywhere | Settings. |
?, F1 |
Everywhere | Help overlay. |
Ctrl+R |
Welcome, lists, Settings, Plugins | Reload the files from disk. |
u, U |
Welcome, Settings | Show the update notice, check for an update now. |
| Space | Plugins | Enable or disable the plugin. |
a, s, i, d, c |
Plugins | Allow (consent), settings, install, remove, check. |
| Esc | Everywhere | Go back, close an overlay. |
Ctrl+L |
A text field with suggestions | Plugin forms (tote 1.1): list the values that the plugin's program suggests, then pick one. |
q |
Everywhere | Quit (not while typing in a field). |
Ctrl+C |
Everywhere | Go back, never quits at once (twice on the welcome page quits). |
Ctrl+D, Ctrl+Z |
Everywhere | Quit, suspend. |
In forms, Tab goes to the next field, Ctrl+S saves and Esc cancels. On a text field of a plugin
form that offers suggestions (choices_from, since tote 1.1), Ctrl+L starts the program that
lists them: nothing starts before that key press, you can always type a value instead, and Esc
(which stops the listing and keeps the form, a second Esc closes it), submitting or closing the form
stops the program. As soon as the program starts, a loading box opens with a spinner, the command
that runs and the seconds it has taken; the list replaces it when it arrives.
Mouse: pointing highlights, a click selects, a double click opens, the wheel scrolls and a click on
a key of the footer presses it. Dragging selects text and copies it when you release the button;
Shift+drag (Option+drag in iTerm2) lets the terminal select instead. ui.mouse turns it all off.
Looks: the theme is auto (follows the terminal background), dark (for a dark terminal), light
(for a light one) or mono; tote paints no background of its own, so a theme set against the
terminal can be unreadable, and the Settings screen warns about it when the terminal has said what
its background is (d goes back to auto); the welcome page is box, compact or off; below 70
columns or 20 rows the welcome box is replaced by a one-line header; the page width can be capped at
120 or 160 columns. Languages: English and French, from TOTE_LANG, then the lang setting, then
LC_ALL, LC_MESSAGES and LANG.
tote 1.1.0 is the current release, 1.0.0 was the first. The channels (State is the first version that had the channel):
| Channel | State | Notes |
|---|---|---|
| Install script | 1.0.0 | Downloads the archive for your system from GitHub Releases, checks its SHA-256 against the signed checksums file, verifies the minisign signature when a verifier is available, installs to ~/.local/bin and writes an install receipt. Never uses sudo, never edits your startup files. Run curl -fsSL https://dropr.sylvain.sh/bash/tote@latest/install.sh | sh, or ... | sh -s -- 1.1.0 for a given version. |
| Release archives | 1.0.0 | tote_<version>_<os>_<arch>.tar.gz for Linux and macOS, amd64 and arm64, with tote_<version>_checksums.txt and its minisign signature. |
.deb |
1.0.0 | tote_<version>_linux_<arch>.deb on GitHub Releases, not tied to an apt source: to update, download the new file and run sudo apt install ./tote_<version>_linux_<arch>.deb. tote never updates itself. |
| Ubuntu PPA | 1.0.0 | sudo add-apt-repository ppa:totecli/tote && sudo apt install tote. Ubuntu 22.04, 24.04 and 26.04 on amd64 and arm64 (Linux Mint 22 uses the 24.04 packages). Update with sudo apt update && sudo apt upgrade tote. Stable releases only. There is no apt repository for Debian: use the .deb. |
go install |
1.0.0 | Needs Go 1.26 or later. |
| From source | works now, in a checkout | See below. |
With Go 1.26 or later:
go install github.com/totecli/tote/cmd/tote@latestOr from a clone of the repository:
git clone https://github.com/totecli/tote.git && cd tote
make build VERSION=1.1.0-local # writes bin/toteA build from source or go install has no release key: tote update refuses to install anything
(tote update --check still looks for a release; in the Go bin folder it prints the go install
command instead) and tote doctor warns. That is expected. The public minisign keys of the
releases:
# current: RWTTj50yYWk72oCPtVJZ8hrpENxKKpQHDtQl3l1JkOxauemhwepIFON3 next (kept offline): RWS7eI0zAwZGD3nDouKjNMVgt3opeJ9Lf3K3RNRKeNYIV1Hm9L0UirQT
sha256sum -c tote_1.1.0_checksums.txt --ignore-missing # macOS: shasum -a 256 -c, on your line
minisign -V -H -P <public key> -m tote_1.1.0_checksums.txt # reads the .minisig next to itA program cannot change the directory of the shell that started it, nor type on its prompt. tote does both through a small shell function that you load once:
For bash, add this line to ~/.bashrc:
eval "$(tote init bash)"For zsh, add this one to ~/.zshrc:
eval "$(tote init zsh)"tote init <bash|zsh> prints the code and writes nothing. It gives you:
- A
totefunction around the binary. It hands the binary a private temporary file (TOTE_HANDOFF) and then does what the binary left in it:cdinto a repository, put a command on your prompt (bashread -e -i, zshprint -z), reload the definitions, or exit. This is why Enter on a repository changes your directory. - Your aliases and functions as real shell aliases and functions. Each repository also becomes an
alias that runs
tote repo open <name>, so typing its name goes there. - The
binfolder of the data directory added to yourPATH. - Tab completion of commands, connection names, plugin ids and the main flags, for bash and for zsh
(when
compinitis loaded). - A reload after you change records in the interface, so new aliases work without a new shell.
tote init <shell> --defs prints only the definitions (aliases, functions, PATH line and
completion), which is what the reload runs. Without the integration the program still works, but
cd cannot happen: tote repos open then only prints the path. tote doctor tells you whether the
line is in place. Names that the shell or tote needs (tote, source, eval, keywords, ...) are
refused for a record.
The private file is made in $XDG_RUNTIME_DIR, else $TMPDIR, else /tmp; if none can be used,
the function says so once and runs the binary without cd and without putting a command on the
prompt. A relative path handed back for cd is made explicit (./name), so CDPATH is never
consulted.
tote help lists them and tote help <command> prints the usage. Commands that list records print
a table on a terminal and tab separated lines in a pipe; --format table|tsv|json chooses and
--json means --format json. The tab separated columns are positional and a later release only
appends columns; every JSON document starts with "schema": 1 and only gains fields (see
docs/compat.md). A name must be unique across aliases, repositories and functions,
because each becomes a word of your shell.
The commands are co (also connections), alias (a), repos (repo, r), funcs (f),
plugin (plugins), config, doctor, update, uninstall, init, version and help. With
no command, tote opens the interface, and --ascii draws it with plain ASCII symbols.
--no-plugins (before the verb) turns every plugin off for one run, like TOTE_NO_PLUGINS=1.
tote co -l [--format table|tsv|json | --json]
tote co <name|alias> [user]
tote co add <name> --target <host> [--via <command>] [--user <user>] [--alias <a,b>] [--ip <ip>] [--desc <text>]
tote co rm <name> [--yes]
tote co <name> replaces tote by ssh. A unique prefix of a name or alias works once it has
connect.prefix_min characters (2 by default), and a second argument overrides the login user.
--via is a command using {user@}, {user}, {host}, {ip} and {name}; empty means plain
ssh. A plain ssh gets keepalive options unless your ssh configuration sets its own. The command
is split on spaces and runs without a shell: quotes are not interpreted (and are refused), so put
options such as ProxyCommand in ~/.ssh/config. Its first word is a command name found through
PATH: it starts with a letter, a digit or _, so an absolute path (/usr/bin/ssh) and ./ssh
are refused. tote doctor warns when that program is not found.
tote co add jump --target 10.0.0.5 --desc "behind the bastion" \
--via 'ssh -t [email protected] {user@}{host}'
tote co add web --target host1.example.org --user admin --alias w,www
tote co web deploy # same connection, other login usertote alias [list] [--format table|tsv|json | --json]
tote alias add <name> [--desc <text>] <command>
tote alias rm <name> [--yes]
tote alias add ll --desc "long listing" "ls -la"tote repos [list] [--format table|tsv|json | --json]
tote repos open <name>
tote repos add <name> <path> [--desc <text>]
tote repos rm <name> [--yes]
A <path> must be absolute or start with ~/; a relative one such as work/app is looked up under
repos_root and used when that folder exists there. tote repos open changes the directory (with
the shell integration) or prints the path. In the interface, o opens the repository in editor
(else $VISUAL, $EDITOR, vim) and repos.after_open decides what follows: return to the
list, quit or cd.
tote repos add app ~/work/app --desc "main application"tote funcs [list] [--format table|tsv|json | --json]
tote funcs add <name> --script <path> [--kind exec|source] [--desc <text>] [--managed]
tote funcs rm <name> [--yes]
--kind source (the default) defines a shell function that sources the script, so it can change
your shell. --kind exec only reserves the name: tote lists it and defines nothing, and the program
itself lives in the bin folder of the data directory or in PATH. add does not check that it
exists, and tote doctor does not look at it. tote doctor does warn about a repository whose path
is not an existing directory and about a source function whose script is missing. A function name
may contain - (fn-x); bash in POSIX mode (bash --posix, sh linked to bash,
POSIXLY_CORRECT=1) refuses such a name, so use letters, digits and _ only if your startup file
is read in that mode. --managed records that the script belongs to tote; the flag is stored and
shown, and nothing so far deletes or moves the file. A later release may act only on scripts under
the bin folder of the data directory (see docs/compat.md).
tote funcs add deploy --script ~/scripts/deploy.sh --desc "push to production"tote plugin [list] [--format table|tsv|json | --json]
tote plugin info <id> [--json]
tote plugin install <source> [--sha256 <hex>] [--grant <token>] [--dry-run] [--force] [--json]
tote plugin update <id> [<source>] [--sha256 <hex>] [--grant <token>] [--dry-run] [--force] [--json]
tote plugin enable <id> [--grant <token>] [--json]
tote plugin disable <id> [--json]
tote plugin remove <id> [--yes] [--purge] [--json]
tote plugin check [<id|dir|archive>] [--strict] [--official] [--argv [--set <field=value>] [--repo <name>]] [--json]
Exit codes: 0 done, 1 failure, 2 usage or a flag is needed, 3 authentication required, 4 refused
(state, policy, --grant mismatch), 5 integrity; update --check adds 10, 127 means a program
could not be started and 130 an interruption (Ctrl-C at the question, or SIGINT or SIGTERM at any
step, a download included; nothing is changed). Codes 6 to 9 and 11 and above are kept for later
releases. See Plugins and docs/compat.md.
tote config # opens the settings on a terminal
tote config path # the directory of config.toml and the record files
tote doctor [--json] # checks, with a fix for each warning
tote doctor --reset # restores a broken terminal, nothing else
tote update [--check] [--json] [--beta] [--force]
tote uninstall [--yes] [--shell] [--purge] [--dry-run]
tote init <bash|zsh> [--defs]
tote version [--json]
tote help [command]
doctorruns more than twenty checks (version, install receipt,PATH, directories and files, name clashes, shell integration,sshandgit,TERM, locale, colors, mouse, clipboard, size, tmux, the update key). Its exit code is 0 when no check failed and 1 when one did; warnings do not change it.update --checkexits 0 when up to date and 10 when a release is available;--betaalso offers pre-releases and--forceinstalls even an older or the same release. With--jsonan error is{"schema": 1, "ok": false, "status": "error", "error": {"code", "message", "exit"}}on standard output, withcodeone ofoffline,rate_limited,no_release,bad_signature,unknown_key,bad_checksum,bad_key,interruptedand so on. A misuse of the command (an unknown option, an extra word) is the same object withcodeusageand exit 2, also when--jsoncomes before or after the bad option, but not after--.uninstallremoves the program and keeps your data.--purgedeletes the data too, that is the record files,config.toml, the plugins with their consent and settings, the plugin lock, the install receipt and the update cache, and nothing else (a folder of your own, or a backup next to the files, stays);--shellalso removes the line that loads tote from your startup files,--yesskips the questions,--dry-runprints the plan and removes nothing. The exact list is in docs/compat.md.
Directories follow the XDG rules; a TOTE_*_DIR variable overrides one and must be absolute.
| Purpose | Variable | Then | Default |
|---|---|---|---|
| Config: records and settings | TOTE_CONFIG_DIR |
$XDG_CONFIG_HOME/tote |
~/.config/tote |
Data: plugins, a bin folder for PATH |
TOTE_DATA_DIR |
$XDG_DATA_HOME/tote |
~/.local/share/tote |
| State: install receipt, plugin lock | TOTE_STATE_DIR |
$XDG_STATE_HOME/tote |
~/.local/state/tote |
| Cache: update check, plugin caches | TOTE_CACHE_DIR |
$XDG_CACHE_HOME/tote |
~/.cache/tote |
The config directory holds config.toml (settings and [plugins.<id>] tables), connections.toml,
repos.toml, aliases.toml, funcs.toml, and plugins/<id>.toml (the settings of a plugin).
Every file that tote writes starts with schema = 1, is plain text and safe to edit while tote is
not writing; a .lock file next to it serialises writers. tote doctor reports a file that does
not parse (with line and column) and warns when the directory or a file can be changed by other
users. A record file that does not parse, or has another schema, is read-only. config.toml is
lenient: an unknown key or an invalid value is reported on standard error with its line and the
default applies; only a syntax error or a schema other than 1 sets the whole file aside. Data that a
plugin keeps goes to plugins.lock or plugins/<id>.toml, never to the [plugins.<id>] tables of
config.toml. Formats stay compatible within 1.x, see docs/compat.md. A record is
a [[connection]] (or [[repo]], [[alias]], [[func]]) table, for example name = "web",
target = "host1.example.org", user = "admin", aliases = ["w", "www"], desc = "Web host".
config.toml with every setting at its default (all optional):
schema = 1
lang = "" # "en", "fr", or empty to follow the environment
editor = "" # empty: $VISUAL, then $EDITOR, then vim
repos_root = "" # folder offered for a new repository, base of relative paths
[connect]
prefix_min = 2 # characters needed before a prefix connects
after_disconnect = "menu" # "menu" or "exit"
keepalive = true
[repos]
after_open = "return" # "return", "quit" or "cd"
[shell]
compat_mn = false # also define a function named mn
extra_names = [] # more function names to expose
[update]
check = true # look for a release in the background, at most once a day
[ui]
theme = "auto" # "auto", "dark", "light" or "mono"
welcome = "box" # "box", "compact" or "off"
compact = "auto" # "auto", "always" or "never"
width = "auto" # "auto", "120" or "160": caps the page at that many columns
mouse = true| Variable | Effect |
|---|---|
TOTE_CONFIG_DIR, TOTE_DATA_DIR, TOTE_STATE_DIR, TOTE_CACHE_DIR |
Directory overrides. |
TOTE_LANG |
Language of the interface (en or fr), before the lang setting. |
TOTE_COLOR |
truecolor, 256, 16, none (also never, off), always or auto. |
NO_COLOR |
Any non-empty value turns the colors off; TOTE_COLOR wins over it. |
TOTE_NO_PLUGINS |
Any value other than empty, 0, false, no or off turns every plugin off for the run. |
TOTE_PLUGIN_<ID>_<SETTING> |
The value of a plugin setting (each hyphen of the id becomes two underscores: my-tool and x give TOTE_PLUGIN_MY__TOOL_X). |
TOTE_UPDATE_BASE, TOTE_UPDATE_PUBKEY |
Read releases from a mirror (https:// or file://); the key override works only with a file:// mirror and never for root. For tests. |
TOTE_HANDOFF and TOTE_SHELL are set by the shell function and are not meant to be set by hand.
A plugin adds commands to the palette and actions to the rows of a list. In tote 1.x a plugin is
declarative: a folder with a plugin.toml and optional translations, with no code of its own.
The manifest lists the programs to run (git, curl, gft), their arguments and the form to ask
first. tote builds each command line itself, one argument per element, and never runs a shell. The
exec tier, where a plugin ships its own program, is reserved for a later version: a manifest
that asks for it is refused, and tote plugin run does not exist in 1.x.
Consent comes first. Before a plugin is installed, or when an update asks for more, tote shows every
command in full and what the plugin declares (programs, files, network, environment variables, the
terminal), marking what tote enforces and what is only declared. Nothing runs before you agree, a
plugin whose files changed after you agreed is refused, and any plugin can be switched off with one
command. The programs a plugin names still run with your rights: read the list. Since tote 1.1 a
plugin can also suggest values for a text field with a program that you start with Ctrl+L; its
argv is shown at consent and an update that adds one asks again.
The plugin that ships with tote is gft. It is embedded in the binary, listed as available
until you install it, and needs the gft program (GitHub releases and Git stashes). On a saved
repository with a GitHub remote (Tab on the row) it adds: show the latest release, its assets and
its notes; list, show, drop and delete stashes. In the palette (>) it adds: show a GitHub release,
open its page, download an asset, install a release binary.
Look first, nothing changes:
tote plugin # list: gft is "available"
tote plugin install gft --dry-run # read what it asks for
tote plugin check gft # the commands it would run, and any problemThen, one at a time:
tote plugin install gft # asks on the terminal
tote plugin disable gft # settings and consent are kept
tote plugin remove gft --purge # also delete its settings and dataFrom another source, with the digest you were given:
tote plugin install example/[email protected] --sha256 <64 hex digits>remove also forgets the enabled = false of a plugin you had switched off, so a later install
starts enabled; --purge adds the settings, state, cache and data.
Without a terminal, consent is a token: --dry-run prints the --grant value to pass to install,
which fails if the plugin asks for anything else. A release is a github.com release URL or
owner/repo@tag and needs the SHA-256 its author published; a folder on your machine
(./my-plugin) is not verified at all. The states are enabled, disabled, needs-consent,
missing-dependency, incompatible, broken, quarantined and available. Quarantine turns a
plugin off after failures; a declarative run never counts as one, so it does not occur yet, and
tote plugin enable clears it.
- docs/plugins/AUTHORING.md: write, check, install and release a plugin, step by step.
- docs/plugins/API1.md: the reference of plugin API 1.
- docs/plugins/SECURITY.md: what a plugin can do, and what tote checks.
- docs/plugins/plugin.schema.json: JSON Schema of the manifest.
- docs/compat.md: what stays compatible in the 1.x line (files, JSON, exit codes).
tote update reads the releases of totecli/tote over https, downloads the archive for your
system, checks it against the checksums file, verifies the minisign signature of that file with the
release keys built into the binary, checks that the new binary announces the expected version, and
replaces the running one atomically. A signature that does not verify is always an error. Versions
are SemVer; stable is the default channel and pre-releases (1.1.0-beta.1) are offered only with
--beta.
An install receipt (install.json in the state directory) records how tote was installed, the
version, the channel and the signed timestamp of the release, and is used to refuse a downgrade. It
stays at schema 1: later releases only add optional fields, which an older tote keeps. A tote owned
by a package manager (apt, Homebrew, go install) never updates or removes itself: tote update
and tote uninstall print the command to run. With update.check on, tote looks for a release in
the background at most once a day, and u on the welcome page reads the notice; nothing is
installed without tote update.
- At least 24 columns by 7 rows; below that the interface asks for a larger terminal. The full layout needs about 70 by 20, smaller terminals get the compact one.
- A UTF-8 locale for the symbols. With another locale, in the Linux console or with
--ascii, tote draws plain ASCII and unaccented text. - Colors are detected: truecolor is optional, and
TOTE_COLOR,NO_COLORor themonotheme turn them down or off. - Clipboard: selecting text or pressing
Ccopies it. tote trieswl-copy(Wayland),xclip, thenxsel(X11), and otherwise sends an OSC 52 sequence to the terminal. GNOME Terminal and other VTE based terminals ignore OSC 52: installxclip,xselorwl-clipboardthere, or select with Shift+drag and copy with Ctrl+Shift+C.wl-copyis used only whenWAYLAND_DISPLAYis set,xclipandxselonly whenDISPLAYis set. On macOS there is nopbcopypath: copying uses OSC 52, so use a terminal that supports it (iTerm2, kitty, WezTerm, Ghostty) or select with Option+drag and use the terminal's own copy. Inside tmux, OSC 52 needsset -g set-clipboard on.tote doctorshows what applies to your session.
tote doctorEach line is OK, WARN or FAIL, and every warning prints its fix (shell integration line
missing, directory not in PATH, a file that does not parse, a name used twice, no clipboard tool,
...).
If a program left your terminal in a bad state (no echo, garbage after a crash), run
tote doctor --reset: it restores the terminal and does nothing else, and needs a terminal on
standard output. If the interface looks wrong, try tote --ascii, TOTE_COLOR=none tote or the
mono theme; to rule a plugin out, run tote --no-plugins. tote config path shows where your
files are.
- Records edited by hand. A record whose
viaholds a quote, or whose text field (cmd,path,script,target,via, ...) is longer than 4096 bytes, is refused byaddand by the forms, and when it is already in a file it loads as invalid: the file stays usable,tote doctornames the line, the shell skips the record andtote co <name>refuses it until you edit it. A record file is also refused for writing when it would pass 4 MiB. - Inserted bash lines. The line that tote puts on your prompt runs inside the
totefunction, so adeclareortypesetat its start is local to that function. Assignments,export,cdand the rest work as usual. Fixing it needs the line to run at the top level of the shell; that is planned for a later release. - Function names with a dash are valid, but bash in POSIX mode refuses to define them.
- Names are checked, not locked. The rule that a name is unique across aliases, repositories and
functions is checked before each
add, not under one lock: twototeprocesses adding the same name at the same moment can both succeed.tote doctorthen reports the clash and the shell keeps the first one. - Closed terminal. SIGINT and SIGTERM stop an install or an update cleanly (exit 130, nothing
changed). SIGHUP, a closed terminal, ends the process at once; what it left in the
.stagingfolder of the plugins is removed by a later install, after one hour. - Translations. Most refusals are translated, but a few messages stay in English: the free text
of a syntax error in a TOML file, an I/O error of the system and some details of
tote doctor. - Exec plugins. A manifest that asks for the exec tier is refused and
tote plugin rundoes not exist: both are planned for a later release, with theghrelandghsecplugins.
The program has no import command. A separate Bash script (bash 4 or later), scripts/import.sh,
does the move. It is in the repository only, not in the release archives or the packages: clone
https://github.com/totecli/tote.git, or download scripts/import.sh from the tag of your version
(https://raw.githubusercontent.com/totecli/tote/v1.1.0/scripts/import.sh). It is a dry run unless
you pass --apply:
bash scripts/import.sh # dry run: shows what would be imported, writes nothingWhen the result is what you expect, run it for real:
bash scripts/import.sh --apply--from DIR and --to DIR choose other locations than the defaults.
Other options: --home DIR, --system-bin DIR, --verbose and --help, the full reference. By
default it reads .config/mn in the home of your account and writes to the tote configuration
directory.
- It moves connections, aliases, repositories and functions. The language and editor files, the
repository list file, the plugins, the docs and the files mn generates are left behind on purpose.
A function is only referenced by its script (
.local/bin/NAME, else/usr/local/bin/NAME), which is never moved, copied or managed. - Every value is checked with the rules of tote. A record that fails is skipped with its reason; the exit status is 1 when something was skipped. Aliases, repositories and functions share one namespace in tote, so when a name clashes the first one wins, in that order.
- It never writes below the mn directory, never changes an existing tote record, can be run again without importing anything twice, and refuses to run as root.
- With
--apply, each tote file it changes is first copied toFILE.bak-<date>-<time>, and the new records are checked in the files afterwards.
Read the dry run first, then check the result with tote co -l, tote repos and so on.
Read the Conventions below first. The Makefile targets:
| Target | What it does |
|---|---|
make build |
Build bin/tote; takes VERSION= and, for a release build, KEYS= (the minisign public keys that tote update trusts). |
make test |
Everything, in several minutes: unit tests, view frames against internal/ui/testdata, terminal injection probes and the tmux end-to-end tests (skipped without tmux, unless TOTE_REQUIRE_TOOLS=1 or CI=true, which make a missing tool a failure). |
make short, make e2e |
The same without tmux, and only the tmux end-to-end tests. |
make race |
The race detector on the interface, updates, command line and end-to-end tests; needs a C toolchain and takes about half an hour (each package has a 30 minute limit). CI does not race the interface tests: run it before every release. |
make check |
gofmt, scripts/docs.sh (Markdown), go vet, golangci-lint, the tests and govulncheck; golangci-lint and govulncheck must be installed. |
make cover, make slow |
Coverage of internal/ui; the single core end-to-end passes. |
make golden |
Rewrite the reference frames; review them with git diff internal/ui/testdata. |
make snapshot |
Release dry run in dist/, unsigned and uploaded nowhere; needs goreleaser v2. See docs/RELEASING.md. |
The tools that make check and make snapshot call are not part of the repository. Install them
once (the binaries land in $(go env GOPATH)/bin, which must be in your PATH):
go install github.com/golangci/golangci-lint/v2/cmd/[email protected]
go install golang.org/x/vuln/cmd/[email protected]
go install github.com/goreleaser/goreleaser/v2@latest
export PATH="$(go env GOPATH)/bin:$PATH"go install needs the network, and so does govulncheck, which reads the vulnerability database.
MIT, see LICENSE.
- Language: everything is in English first (code, comments, commits, documentation, releases, visuals). The interface is English by default, with French as a second language.
- Branch: work happens on
master. - Commits: a single subject line,
SEVERITY: scope: Description, no body. SeveritiesMAJOR,MEDIUM,MINOR,BUILD,DOC; scopescmd,ui,config,store,shell,plugin,i18n,update,scripts(the folder name);BUILDandDOChave no scope. One scope per commit, signed. - Commit check: CI runs
scripts/commits.shon every push tomasterand on pull requests (format and single line). It can be run locally on any range, for examplescripts/commits.sh origin/master..HEAD. There is no git hook. - Markdown: prose lines stay within 100 columns (tables and fenced code are left alone).
scripts/docs.shchecks it, inmake checkand in CI. - Releases: signed tag with a
vprefix (v1.0.0, asgo installrequires), empty release title. Betas (1.1.0-beta.1) are GitHub pre-releases, installed with the script or, once tote is installed, withtote update --beta; never published to the PPA. - Dependencies: only Bubble Tea v2, Lip Gloss v2, a few Bubbles packages (
keyandtextinput),x/ansi,charmbracelet/colorprofile(color detection, Charm family), a TOML library,golang.org/x/crypto(theblake2bpackage only, to verify update signatures) andgolang.org/x/sys/unix(terminal size fortote doctor). Charm imports,colorprofileincluded, stay insideinternal/ui/. - No migration in the app: moving data over from mn is a separate script described in this README, never a command of tote.
- Instructions for contributors live in this README (this section), not in a per-tool instruction file.