nushell-plugins/nu_plugin_auth/quick-reference.md

nu_plugin_auth Quick Reference

Version: 0.1.0 Status: Login/Logout Commands Implemented

---

Installation

nushell
# Build plugin
cargo build --release -p nu_plugin_auth

# Register with Nushell
plugin add target/release/nu_plugin_auth
plugin use nu_plugin_auth

---

Login Command

Basic Usage

nushell
# Interactive login (password prompt)
auth login admin

# Login with password
auth login admin mypassword

# Login and save to keyring
auth login admin --save

# Custom Control Center URL
auth login admin --url http://control.example.com:8081

Flags

Flag	Short	Type	Description	Default
--url	-	String	Control Center URL	http://localhost:8081
--save	-	Switch	Save tokens to keyring	false

Output

nushell
{
  success: true,
  user: {
    id: "user-123",
    username: "admin",
    email: "admin@example.com",
    roles: ["admin", "developer"]
  },
  expires_in: 900,
  token_saved: true
}

---

Logout Command

Basic Usage

nushell
# Logout current user
auth logout

# Logout specific user
auth logout --user admin

# Logout all sessions
auth logout --all

Flags

Flag	Short	Type	Description	Default
--user	-u	String	Username	Current system user
--url	-	String	Control Center URL	http://localhost:8081
--all	-a	Switch	Logout all sessions	false

Output

nushell
{
  success: true,
  message: "Logged out successfully",
  user: "admin"
}

---

MFA Commands (Bonus)

TOTP Enrollment

nushell
# Enroll in TOTP
auth mfa enroll totp

# Enroll for specific user
auth mfa enroll totp --user alice

Output: QR code in terminal + secret + backup codes

TOTP Verification

nushell
# Verify TOTP code
auth mfa verify --code 123456

# Verify for specific user
auth mfa verify --code 123456 --user alice

WebAuthn Enrollment

nushell
# Enroll WebAuthn (YubiKey, Touch ID)
auth mfa enroll webauthn

---

Security Features

• ✅ OS Keyring: Secure credential storage (Keychain, libsecret, Credential Manager)
• ✅ No Echo: Password input not visible in terminal
• ✅ HTTPS: TLS with rustls (no OpenSSL)
• ✅ JWT Tokens: RS256-signed access + refresh tokens
• ✅ Token Revocation: Server-side blacklist on logout

---

Error Handling

nushell
# No active session
auth logout
# Error: No active session: No token found

# Invalid credentials
auth login baduser wrongpass
# Error: Login failed: HTTP 401 - Invalid credentials

# Network error
auth login admin --url http://invalid:8081
# Error: HTTP request failed: connection refused

---

Platform Support

Platform	Credential Storage
macOS	Keychain
Linux	Secret Service (libsecret/gnome-keyring)
Windows	Credential Manager

---

API Endpoints

Endpoint	Method	Description
/auth/login	POST	Authenticate and get tokens
/auth/logout	POST	Revoke access token
/auth/verify	GET	Verify token validity
/auth/sessions	GET	List active sessions
/mfa/enroll/{type}	POST	Enroll in MFA
/mfa/verify	POST	Verify MFA code

---

Workflow Examples

Standard Login/Logout

nushell
# Login
auth login admin --save

# Do work...

# Logout
auth logout

Multiple Users

nushell
# Login as different users
auth login alice --save
auth login bob --save

# Logout specific user
auth logout --user alice

CI/CD Integration

nushell
# Non-interactive login
let token = auth login $env.CI_USER $env.CI_PASS | get user.id

# Use token for operations...

# Cleanup
auth logout --user $env.CI_USER

---

Troubleshooting

"No token found" error

Cause: No active session or keyring not accessible Fix: Login again with --save flag

"HTTP request failed"

Cause: Control Center not running or wrong URL Fix: Check Control Center status and --url flag

"Login failed: HTTP 401"

Cause: Invalid credentials Fix: Verify username and password

Keyring access denied

Cause: OS permission issue Fix: Grant keychain/keyring access to plugin binary

---

Development

Build Commands

bash
# Check code
cargo check -p nu_plugin_auth

# Build debug
cargo build -p nu_plugin_auth

# Build release
cargo build --release -p nu_plugin_auth

# Run tests
cargo test -p nu_plugin_auth

Plugin Location

• Source: provisioning/core/plugins/nushell-plugins/nu_plugin_auth/
• Binary: target/release/nu_plugin_auth

---

Related Commands (Future)

• auth verify - Verify current token
• auth sessions - List all sessions
• auth whoami - Show current user
• auth refresh - Refresh expired token

---

Last Updated: 2025-10-09 Documentation: See LOGIN_LOGOUT_IMPLEMENTATION.md for complete details