Skip to main content

Identity Commands (modal id)

Create a New Identity​

# Create with default path
modal id create --path alice.passfile

# Create with passfile encryption
modal id create --path alice.passfile --encrypt

# Create in the standard passfile directory
modal id create --name alice

# Namespace identities under ~/.modality/passfiles/<namespace>/
modal id create --name example/alice

modal id create writes a passfile. Use --path <PATH> for an explicit location, --dir <DIR> for an output directory, or --name <NAME> for the standard ~/.modality/passfiles/<name>.mod_passfile location. Names may include / namespaces, so --name example/alice writes:

  • ~/.modality/passfiles/example/alice.mod_passfile — private key
  • ~/.modality/ids/example/alice.id — public ID only

modal c set-named-id reads the public ID. modal c commit --sign reads the passfile. Both resolve the same names:

modal c set-named-id /parties/alice.id example/alice
modal c commit --all --sign example/alice

Derive Sub-Identity​

modal id derive --mnemonic "abandon abandon ..." --path alice-escrow.passfile

Derives a keypair from a BIP39 mnemonic seed phrase. Useful for:

  • Contract-specific keys
  • Rotating access keys
  • Hierarchical key management

Get Public ID​

modal id get --path alice.passfile
# Output: ed25519:abc123...

modal id get --name example/alice

Passfile Operations​

Encrypt a Passfile​

modal passfile encrypt --path alice.passfile

Decrypt a Passfile​

modal passfile decrypt --path alice.passfile

Best Practices​

  1. Protect your passfiles — They contain your private keys
  2. Use password encryption for long-term storage
  3. Derive sub-keys for different contracts
  4. Back up your identity key — It represents your identity
  5. Keep named passfiles out of the contract directory — store them under ~/.modality/passfiles/