Command line

The mesgd launcher starts a local node and provides command-line access to a running one. Use it to check connectivity, attach an Erlang shell, manage accounts, and test claim tokens. Remote operations authenticate through the Erlang distribution cookie, so access to the launcher and cookie carries the authority of a node operator.

mesgd [node] command

If the first argument contains @, it is the node name. Otherwise the node is mesgd@localhost and the first argument is the command.

mesgd help
mesgd status
mesgd start
mesgd stop
mesgd console
mesgd observer
mesgd forge sub alice room lobby
mesgd check /room=lobby TOKEN
mesgd otp USER
mesgd user help

command help prints that command's help. When mesgd refuses a user command, the shell prints User command failed: and the reason.

status prints ok when the shell can connect, and fail when it cannot. A failure means the cookie or the node name did not match. It does not, by itself, mean the mesgd process has stopped.

console attaches a shell on the node. observer opens the Erlang observer against the node. Both need the distribution cookie. See Configuration.

stop stops the mesgd application on the node. It leaves epmd running.

Test claim tokens

mesgd forge builds a claim token from name and value pairs. A final name with no value is set to true.

mesgd forge sub alice room lobby
mesgd check /room=lobby TOKEN

check asks the node whether that token is accepted for the path and prints ok or fail. The forged token carries the claims you supplied and can be used where those claims authorize a path. It does not create a login session or save a permission or role. To store paths and hand a program a token that follows them, use message access. The three tokens are compared in Routing.

Read a current authenticator code

mesgd otp USER

The command prints the current six-digit authenticator code for an active user without exporting the stored secret or consuming the code. Pending accounts return inactive_user; user add confirms its enrollment using the signup secret instead. This operation is available only through the trusted node interface.

Use this when you are on the node and you need a code for an account you already operate. Do not expose it as a network service.

Manage accounts

Account commands write files in the current directory and print the paths. They do not take a filename argument. A name looks like mesgd-<user>-<purpose>-<time>-<random>. Characters outside letters, digits, ., _, and - become _, so @ does. A later command reads the newest matching file. The files are readable only by the account that ran the command.

mesgd user list
mesgd user show USER
mesgd user add EMAIL
mesgd user confirm USER
mesgd user password USER
mesgd user reset USER
mesgd user disable USER
mesgd user enable USER
mesgd user unlock USER
mesgd user revoke USER
mesgd user remove USER
mesgd user hard-reset USER
mesgd user recover USER

Command	When you use it
`list`, `show`	See account metadata. Credentials are omitted
`add EMAIL`	Create an active account. mesgd generates the password, confirms the authenticator, and writes the password, authenticator, QR, and recovery files. It prints `Enrolled` and the paths
`confirm USER`	Finish a signup that is still pending, using the newest enrollment file, then delete that file
`password USER`	Write a new password file
`reset USER`	Replace a forgotten password when the authenticator still works. mesgd uses the first code in the newest recovery file and a local authenticator code, then writes a new password file and a new recovery file
`enable USER`	Activate a pending account, or turn a disabled account back on. Any other status fails with `bad_request`
`disable USER`	Block login, recovery, and existing sessions
`unlock USER`	Clear a failure lockout. A disabled account stays disabled
`revoke USER`	End that user's sessions
`remove USER`	Retire the account and keep the name from public signup
`hard-reset USER`	Replace the account, including a retired one, drop provider links, and enroll a new password and authenticator. Grants and other properties stay
`recover USER`	Write a handoff file with `recovery_token` for a lost authenticator. The person enters that code on `/account` under "Lost your authenticator?"

enable on a pending account makes it active and clears the enrollment token. It does not issue recovery codes. Login still needs the password and authenticator from user add.

reset uses up one recovery code. A code just used by add is rejected until the next authenticator step. A wrong recovery code returns unauthorized and does not use up the authenticator code.

These commands record the reason Node console administration, with a more specific reason for password, reset, and recover. Password change, disable, enable, unlock, revoke, remove, hard-reset, and the recovery handoff have no public HTTP route. Allowlisted administrators use the administration API instead. There is no HTTP route for hard-reset.

MESGD_COOKIE_FILE is described in Configuration. MESGD_EBIN is described in Building.