MUTN/docs/man

.TH MUTN 1 "15 July 2024" "v0.2.A" "MUTN man page"

.SH NAME
\fBmutn\fR - Simple, self-hosted, SSH-synchronized password management based on libmutton. It is the successor to sshyp.

.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 (ideally accepting remote connections).

.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                  Change configuration options (NOT YET IMPLEMENTED)
 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

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. Type "mutn" (no arguments/options) to view a list of saved entries

3. Provide "add", "edit", "copy", or "gen" as the only argument to receive more specific help

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

.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.

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

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

.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
TBD

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