muse auth — Identity Management Reference
Muse uses Ed25519 key-pair authentication. Both humans and agents are first-class identities, authenticated identically via challenge-response signing. This command manages the identity lifecycle: key generation, registration, introspection, and logout.
Table of Contents
Identity File
Path: ~/.muse/identity.toml
Permissions: 0o600 (read/write owner only)
Directory permissions: 0o700 (owner only)
File format
TOML with one section per hub hostname. The section key is the bare hostname (no scheme, no path), always lowercase:
["musehub.ai"]
type = "human"
handle = "alice"
algorithm = "ed25519"
fingerprint = "sha256:abc123..."
hd_path = "m/1075233755'/0'/0'/0'/0'/0'"
["staging.musehub.ai"]
type = "agent"
handle = "composer-v2"
algorithm = "ed25519"
fingerprint = "sha256:def456..."
hd_path = "m/1075233755'/0'/0'/0'/1'/0'"
capabilities = ["read:*", "write:midi", "commit"]
IdentityEntry fields
| Field | Type | Required | Description |
|---|---|---|---|
type |
"human" | "agent" |
Yes | Identity type |
handle |
str |
Yes | Registered username on the hub |
algorithm |
str |
Yes | Always "ed25519" |
fingerprint |
str |
No | Public key fingerprint |
hd_path |
str |
No | SLIP-0010 HD derivation path for key derivation |
capabilities |
list[str] |
No | Agent capability strings (empty for humans) |
Security properties
- The file is written with
0o600permissions usingos.open()+os.fchmod(). - Writes are atomic: data goes to a temp file, then
os.replace()renames it. - A symlink at the target path is refused.
- An exclusive advisory lock prevents concurrent write races.
- The private key is never logged or printed.
Commands
muse auth keygen
Generate an Ed25519 key pair for a hub.
muse auth keygen [--hub URL]
muse auth keygen --hub https://musehub.ai
muse auth register
Register a public key with a hub via challenge-response and store the identity.
muse auth register [--hub URL] [--handle NAME] [--agent]
Options:
| Flag | Description |
|---|---|
--hub URL |
Hub URL. Falls back to [hub] url in .muse/config.toml. |
--handle NAME |
Username to register on the hub. |
--agent |
Mark this identity as an agent (default: human). |
Examples:
# Human
muse auth register --hub https://musehub.ai --handle alice
# Agent
muse auth register --hub https://musehub.ai --handle composer-v2 --agent
muse auth whoami
Display the stored identity for a hub.
muse auth whoami [OPTIONS]
Options:
| Flag | Description |
|---|---|
--hub URL |
Hub URL to inspect. Defaults to the repo's configured hub. |
--all / -a |
Show identities for all configured hubs. |
--json / -j |
Emit JSON instead of human-readable output. |
JSON output shape:
{
"hub": "musehub.ai",
"type": "human",
"handle": "alice",
"fingerprint": "sha256:abc123...",
"key_set": true,
"capabilities": []
}
Exit codes:
0— identity found and displayed.- Non-zero — no identity stored for the specified hub.
muse auth logout
Remove stored identity for a hub.
muse auth logout [OPTIONS]
Options:
| Flag | Description |
|---|---|
--hub URL |
Hub URL to log out from. Defaults to the repo's configured hub. |
--all |
Remove identities for ALL configured hubs. |
The identity is deleted from ~/.muse/identity.toml. The hub URL in
.muse/config.toml is preserved — use muse hub disconnect to remove the hub
association from the repository as well.
Authentication Flows
Human flow
# 1. Generate a key pair
muse auth keygen --hub https://musehub.ai
# 2. Register with the hub
muse auth register --hub https://musehub.ai --handle alice
# 3. Push
muse push
Agent flow
muse auth keygen --hub https://musehub.ai
muse auth register --hub https://musehub.ai --handle pipeline-agent --agent
muse push
See also:
docs/reference/hub.md—muse hub connect/status/disconnect/pingdocs/reference/remotes.md—muse push,muse fetch,muse clone