Zerobyte CLI Documentation#

Overview#

Zerobyte is a backup automation tool built on top of Restic. The CLI provides administrative commands for managing users, authentication, and organizational settings outside of the web interface. These commands are particularly useful for troubleshooting, automation, and administrative tasks that require direct system access.

Architecture#

Zerobyte uses a dual-mode architecture where the same application binary can run as either a web server or CLI tool. The application checks for CLI commands at startup, and if a command is detected, it executes the CLI operation and exits before starting the web server.

Technical Stack#

• CLI Framework: Commander.js v14.0.2 for command-line parsing and routing
• Interactive Prompts: @inquirer/prompts v8.3.2 for user-friendly interactive mode
• Mode Detection: Environment variable ZEROBYTE_CLI=1 distinguishes CLI mode from web server mode

Getting Started#

Basic Usage#

The Zerobyte CLI supports two execution modes depending on your environment:

Development Mode:

bun run app/server/cli/main.ts <command> [options]

Production Mode:

ZEROBYTE_CLI=1 bun .output/server/_ssr/ssr.mjs <command> [options]

Command Modes#

All CLI commands support two interaction modes:

• Non-interactive mode: Provide all required information via command-line flags. Ideal for automation and scripting.
• Interactive mode: Omit flags to enter an interactive prompt-based workflow. Best for manual administrative tasks.

Help and Command List#

View all available commands:

zerobyte --help

View help for a specific command:

zerobyte <command> --help

Command Reference#

reset-password#

Reset a user's password. This command updates the password for a specified user account and invalidates all existing sessions, forcing the user to log in again with the new password.

Options#

• -u, --username <username> - Username of the account to reset
• -p, --password <password> - New password for the account

Interactive Mode#

When run without flags, the command provides an interactive workflow:

1. Select username from a list of all users
2. Enter new password with masking (asterisks)
3. Confirm password with matching validation

Validation Rules#

• Password must be at least 8 characters long
• User must exist in the database
• In interactive mode, confirmation password must match the entered password

What Happens#

When a password is reset, the following operations occur in a database transaction:

1. The password is hashed using better-auth
2. If the user has an existing credential account, it is updated with the new password hash
3. If the user has no credential account (e.g., SSO-only user), a credential account is created with the new password
4. A legacy password hash is also maintained for backward compatibility
5. All existing user sessions are deleted from the database, forcing re-authentication

Note: This command can be used to create a credential account for SSO-only users, which is a prerequisite for using the change-email command.

Examples#

# Interactive mode with prompts
zerobyte reset-password

# Non-interactive mode with flags
zerobyte reset-password -u john_doe -p newpassword123

disable-2fa#

Disable two-factor authentication for a user who has lost access to their authenticator device or backup codes. Unlike password reset, this command does not invalidate existing sessions.

Options#

• -u, --username <username> - Username of the account to disable 2FA for

Interactive Mode#

When run without flags:

1. Select username from a list of all users

Validation Rules#

• User must exist in the database
• User must have 2FA enabled (command will fail if 2FA is already disabled)

What Happens#

The command performs an atomic database transaction that:

1. Sets the twoFactorEnabled flag to false in the user record
2. Deletes all 2FA records including TOTP secret and backup codes
3. Existing sessions remain valid—the user is not logged out
4. User can re-enable 2FA from their account settings with new secrets

Examples#

# Interactive mode with prompts
zerobyte disable-2fa

# Non-interactive mode with flags
zerobyte disable-2fa -u john_doe

change-username#

Change a user's username. This command updates the username and invalidates all existing sessions, forcing the user to log in again with their new username.

Options#

• -u, --username <username> - Current username of the account
• -n, --new-username <new-username> - New username for the account

Interactive Mode#

When run without flags:

1. Select the current username from a list of all users
2. Enter the new username with real-time validation feedback

Validation Rules#

• Username format must match pattern /^[a-z0-9_.-]{2,30}$/:
  • 2-30 characters in length
  • Letters (a-z, case-insensitive), numbers (0-9), underscores (_), hyphens (-), and dots (.) are allowed
• Old username must exist in the database
• New username must not be taken by another user
• Usernames are automatically normalized to lowercase and trimmed (e.g., Admin-User becomes admin-user)

What Happens#

The command executes a database transaction that:

1. Updates the username in the users table
2. Deletes all existing sessions for the user, logging them out from all devices
3. User must log in with the new username

Examples#

# Interactive mode with prompts
zerobyte change-username

# Non-interactive mode with flags
zerobyte change-username -u john_doe -n johndoe123

change-email#

Change a user's email address. This command updates the email, deletes all linked SSO accounts (except credential accounts), and invalidates all existing sessions, forcing the user to log in again with their new email.

Options#

• -u, --username <username> - Username of the account
• -e, --email <email> - New email for the account

Interactive Mode#

When run without flags:

1. Select username from a list of all users (displays both username and current email)
2. Enter the new email with real-time validation feedback
3. If SSO accounts will be deleted, displays a warning and requires confirmation to proceed

Validation Rules#

• Email must match the pattern /^[^\s@]+@[^\s@]+\.[^\s@]+$/ (basic email format validation)
• User must exist in the database
• New email must not be the same as the current email
• New email must not be already in use by another user
• User must have a credential account (command will fail if not, suggesting to run reset-password first to create one)
• Email addresses are automatically normalized to lowercase and trimmed

What Happens#

The command executes a database transaction that:

1. Updates the email address in the users table
2. Deletes all linked SSO accounts except credential accounts (OAuth/OIDC providers like Google, GitHub, etc.)
3. Deletes all existing sessions for the user, logging them out from all devices
4. User must log in with the new email

Important: If the user had linked SSO accounts (e.g., Google, GitHub), they will need to be re-invited with the new email address to regain SSO access to those providers. The command shows a warning and requires explicit confirmation before proceeding when SSO accounts will be deleted.

Examples#

# Interactive mode with prompts
zerobyte change-email

# Non-interactive mode with flags
zerobyte change-email -u john_doe -e newemail@example.com

rekey-2fa#

Re-encrypt all two-factor authentication secrets using the current APP_SECRET environment variable. This command is used when migrating from legacy restic.pass-based encryption to APP_SECRET-based encryption.

Use Case#

In earlier versions of Zerobyte, 2FA secrets were encrypted using the restic repository password. The system now uses a dedicated APP_SECRET for database encryption. This command migrates existing 2FA secrets from the old encryption scheme to the new one.

Options#

• -s, --legacy-secret <secret> - Legacy better-auth base secret as a string (the content from the restic.pass file)
• -f, --legacy-secret-file <path> - Path to the legacy secret file (defaults to /var/lib/zerobyte/data/restic.pass)

Important: Only one option should be provided, not both.

Validation Rules#

• The -s and -f flags are mutually exclusive
• If using -f, the secret file must not be empty
• File must be readable with proper permissions

How It Works#

1. Derives encryption key from legacy secret using HKDF key derivation
2. Decrypts TOTP secrets and backup codes using the legacy key
3. Re-encrypts the secrets using the current APP_SECRET
4. Updates database records in a transaction

Behavior#

• Processes all users with 2FA enabled
• Collects errors per user but continues processing other users (allows partial success)
• Reports detailed success/failure counts at the end
• Users with failed migrations can use 2FA with the legacy key until re-run successfully

Examples#

# Using legacy secret directly
zerobyte rekey-2fa -s "legacy-secret-value"

# Using legacy secret file
zerobyte rekey-2fa -f /path/to/old/restic.pass

# Using default file location
zerobyte rekey-2fa -f /var/lib/zerobyte/data/restic.pass

assign-organization#

Assign a user to a different organization in a multi-tenant setup. This command invalidates all existing sessions to ensure the user's context reflects their new organization.

Options#

• -u, --username <username> - Username of the user to reassign
• -o, --organization <organization> - Organization slug to assign the user to

Interactive Mode#

When run without flags:

1. Select username from a list of all users
2. Select organization from available organizations (the user's current organization is excluded from the list)

Validation Rules#

• User must exist in the database
• Target organization must exist
• User must not already be assigned to the target organization

What Happens#

The command executes a database transaction that:

1. Updates existing membership or creates a new membership record pointing to the new organization
2. Assigns the user the "member" role in the new organization (not owner or admin)
3. Deletes all existing sessions for the user, logging them out from all devices
4. User must log in again to access the new organization

Note: If you need to assign a different role (owner or admin), you must do so separately through the web interface after assignment.

Examples#

# Interactive mode with prompts
zerobyte assign-organization

# Non-interactive mode with flags
zerobyte assign-organization -u john_doe -o acme-corp

Security Considerations#

• Session Invalidation: Most commands invalidate user sessions as a security measure. Users must re-authenticate after password changes, username changes, email changes, and organization reassignments.
• 2FA Backup: Before disabling 2FA for a user, ensure they have alternative account recovery methods.
• SSO Account Deletion: When changing a user's email, all linked SSO accounts are removed. The user will need to be re-invited with the new email to regain SSO access.
• Secret Management: When using rekey-2fa, handle legacy secrets securely and delete them after successful migration.
• Access Control: CLI commands require direct server access. Restrict CLI execution to authorized system administrators only.

Troubleshooting#

Command Not Found#

Ensure you're using the correct command syntax for your environment (development vs production) and that the ZEROBYTE_CLI=1 environment variable is set in production.

Database Connection Errors#

Verify that database connection settings are properly configured in your environment variables and that the database is accessible from the CLI execution context.

Permission Denied#

Check file permissions for secret files when using the -f flag with rekey-2fa. The file must be readable by the user running the CLI command.