MUTN/docs/man

.TH MUTN 1 "17 February 2026" "v0.4.0" "MUTN man page"

.SH NAME
\fBmutn\fR - Simple, self-hosted, SSH-synchronized password and note management based on libmutton.

.SH SYNOPSIS
Usage: mutn [/<entry name> [argument] [option]] | [argument]

.SH DESCRIPTION
mutn is a lightweight password, TOTP, and note management program for the CLI. MUTN is self-hosted with a client-server model and expects that you have access to a personal server with a properly configured SSH server.

.SH EXAMPLES
Setting up MUTN for the first time:
    mutn init

Viewing the entry database:
    mutn

Reading an existing entry saved as '~/.local/share/libmutton/development/github':
    mutn /development/github

Reading the same entry without hiding the password:
    mutn /development/github show

Removing an existing folder saved as '~/.local/share/libmutton/social':
    mutn /social shear

Copying the password of an existing entry saved as '~/.local/share/libmutton/financial/bank':
    mutn /financial/bank copy

Copying the TOTP token of an existing entry saved as '~/.local/share/libmutton/financial/bank':
    mutn /financial/bank copy -t

Editing the username of an existing entry saved as '~/.local/share/libmutton/game':
    mutn /game edit -u

Making a new entry saved as '~/.local/share/libmutton/school/university' using the built-in password generator:
    mutn /school/university gen

Creating a note-only entry saved as '~/.local/share/libmutton/notes/test note':
    mutn /notes/test\ note add -n

Manually synchronizing entries with the server:
    mutn sync

.SH ARGUMENTS
 help                   Bring up the help menu
 version                Display version and license information
 init                   Set up MUTN (generates libmutton.ini)
 tweak                  Make changes to the libmutton configuration
 copy                   Copy details of an entry to your clipboard
 edit                   Edit an existing entry
 gen                    Generate a new password
 add                    Add a new entry
 shear                  Delete an existing entry
 sync                   Manually sync the entry directory

.SH OPTIONS

copy:
 password|-pw|<blank>   Copy the password in an entry to your clipboard
 username|-u            Copy the username in an entry to your clipboard
 totp|-t                Generate and copy the TOTP token for an entry to your clipboard
 url|-l                 Copy the URL in an entry to your clipboard
 note|-n                Copy the first note line in an entry to your clipboard
 menu|-m                Open interactive menu to copy any combination of fields

edit:
 password|-pw           Change the password in an entry
 username|-u            Change the username in an entry
 totp|-t                Change the TOTP secret in an entry
 url|-l                 Change the URL in an entry
 note|-n                Change the note in an entry
 rename|-r              Rename or relocate an entry

gen:
 update|-u              Generate a password for an existing entry

add:
 password|-pw           Add a password entry
 note|-n                Add a note entry
 folder|-f              Add a new folder for entries

.SH TIPS
1. You can quickly read an entry with "mutn /<entry name>"

2. Using "add", "edit", or "copy" without specifying an option (field) will default to "password"

3. Various changes can be made to the configuration and stored entries from the "mutn tweak" menu

4. Type "mutn" (no arguments) to view a list of saved entries w/colored markers indicating the ages of stored passwords

.SH SETUP
libmutton operates on a client-server model, and thus sync support requires you to have access to your own server (whether it be a physical home server or a cloud rental) with remote access via SSH.

For security reasons, libmutton deliberately does not support password-based SSH authentication; you must use key-based authentication to connect to your server (password-protected keys are also supported). You are responsible for setting up SSH connectivity on your own.

The libmutton server software is shipped as its own dedicated binary and must be installed on the server and configured with "libmuttonserver init".

Once this has been done, you may proceed with the client setup:
    1. Install MUTN
    2. Run "mutn init" and follow the prompts
    3. If you already have entries on the server, sync them using "mutn sync"
    4. Optionally, shell completions (Bash, ZSH, and PowerShell 7+) can be enabled with your shell's respective method
    5. If importing passwords from another password manager, you may desire to use the "Age all entries" option from the "mutn tweak" menu to add initial age tracking data to the imported passwords

.SH TROUBLESHOOTING
.B Clipboard not clearing:

    The intended way for libmutton to interact with the system clipboard is for it to clear it 30 seconds after copying a field. Unfortunately, this does not work by default on all systems due to the prevalence of clipboard managers.

    Clipboard managers save a history of what has been copied to the clipboard, which is already a big enough issue on its own for people who copy sensitive information to their clipboard. Some clipboard managers simply will not allow the clipboard to be empty and will replace its contents with the last copied item if you attempt to clear it. One such naughty clipboard manager is KDE Klipper, which comes packaged into KDE Plasma and is typically enabled by default on most distributions. Due to this behavior, KDE Klipper breaks libmutton's clipboard clearing functionality and should not be left enabled.

    It is likely other popular clipboard managers exhibit this behavior.

.B Shell completions not working:
    ZSH:
        Make sure your ~/.zshrc contains the following (if sourcing from default completions location, usually /usr/share/zsh/functions/Completion/Unix/_mutn):

            autoload -Uz compinit && compinit

        ...and then restart your shell.

    Bash:
        Install your distribution's "bash-completion" package

            OR

        Source the completion script manually by adding the following to your ~/.bashrc (then restart your shell):

                Linux:

                    source /usr/share/bash-completion/completions/mutn

                FreeBSD:

                    source /usr/local/share/bash-completion/completions/mutn

        ...and then restart your shell.

        Please note that Bash completions are slightly more limited than ZSH completions, and as such, new entries will not be auto-completed until the completions script is re-sourced.

    PowerShell 7+:
        Currently, completions must be manually installed and sourced in your PowerShell profile as such:

            . /path/to/mutn.ps1

        ...and then restart your shell.

.SH EXIT CODES (defined by libmutton)
0: no error

101: read error

102: write error

103: target not found

104: sync process error

105: decryption error

106: encryption error

107: clipboard error

.SH AUTHOR
Randall Winkhart (https://github.com/rwinkhart)