CLI Authentication

The DefDrive CLI provides two authentication methods: Signup (create a new account) and Login (authenticate with existing credentials). Both flows include input validation, confirmation steps, and the ability to edit entries before submission. After entering your DefDrive URL, you’re presented with an interactive menu:

Select an option using the arrow keys and press Enter:

> Signup
  Login

Use ↑ and ↓ arrow keys to navigate between options. The > indicator shows your current selection.

Create a new DefDrive account through the CLI. Navigate to “Signup” in the menu and press Enter.

Step 2: Enter Account Details

The CLI prompts for five fields in sequence:

Name

Enter your name:
|

Enter your full name (e.g., “John Doe”)

Enter your email:
|

Provide your email address

Username

Enter your username:
|

Choose a unique username for your account

Password

Enter your password:
|

Create a secure password

The password is displayed as plain text during entry in the current CLI implementation.

Confirm Password

Enter your confirm_password:
|

Re-enter your password to confirm

Step 3: Review and Confirm

After entering all fields, the CLI displays a summary:

Confirm your details:
Name: John Doe
Email: [email protected]
Username: johndoe
Password: ********
Confirm Password: ********

Type 'confirm' to proceed or 'edit' to modify.

Type 'confirm' - Proceed with signup

The CLI validates that passwords match, then sends a signup request to the server.Password Validation:

If passwords don’t match, you’re prompted to re-enter from the password field:

Passwords do not match. Re-enter your password:
|

Successful Signup:

Signup and login successful!

The CLI automatically:

Creates your account via /api/signup
Logs you in via /api/login
Saves token to .defdrive_credentials

Failed Signup:

Signup failed: [error message from server]

Common errors:

Username already taken
Invalid email format
Server connection issues

Type 'edit' - Modify entries

The CLI enters edit mode, allowing you to update any field:

Modify your name:
John Doe|

The current value is pre-populated. You can:

Edit the existing value
Clear it and enter a new value
Press Enter to keep it unchanged

The CLI cycles through all five fields:

Name
Email
Username
Password
Confirm Password

After modifying all fields, you return to the confirmation screen.

When you confirm signup, the CLI sends a POST request to /api/signup:

{
  "name": "John Doe",
  "email": "[email protected]",
  "username": "johndoe",
  "password": "yourpassword"
}

After successful signup, the CLI automatically calls the login endpoint to retrieve an authentication token. Authenticate with an existing DefDrive account. Navigate to “Login” in the menu and press Enter.

Step 2: Enter Credentials

The CLI prompts for two fields:

Username

Enter your username:
|

Enter your DefDrive username

Password

Enter your password:
|

Enter your account password

Step 3: Review and Confirm

The CLI displays your credentials:

Confirm your details:
Username: johndoe
Password: ********

Type 'confirm' to proceed or 'edit' to modify.

Type 'confirm' - Proceed with login

The CLI sends a login request to the server.Successful Login:

Login successful!

The CLI:

Receives authentication token from /api/login
Saves token and username to .defdrive_credentials
Completes the setup

Failed Login:

Login failed: [error message from server]

Common errors:

Invalid username or password
Account not found
Server connection issues

Type 'edit' - Modify credentials

The CLI enters edit mode:

Modify your username:
johndoe|

The current value is pre-populated. You can edit it and press Enter.After modifying username, you’re prompted to modify password:

Modify your password:
|

After both fields, you return to the confirmation screen.

When you confirm login, the CLI sends a POST request to /api/login:

{
  "username": "johndoe",
  "password": "yourpassword"
}

The returned token is stored in .defdrive_credentials for future use.

Edit Mode Details

Both signup and login flows support edit mode for correcting mistakes before submission.

How Edit Mode Works

Type 'edit' at confirmation

Instead of ‘confirm’, type ‘edit’ and press Enter

Cycle through fields

The CLI prompts you to modify each field in order:

Signup: name → email → username → password → confirm_password
Login: username → password

Pre-populated values

Each field shows your previous entry, which you can:

Edit using backspace and typing
Navigate with ← → arrow keys
Press Enter to keep unchanged and move to next field

Return to confirmation

After modifying all fields, you’re shown the updated summary and can ‘confirm’ or ‘edit’ again

Edit Mode Flow States

The CLI uses internal step tracking for edit mode:

Flow	Confirmation Step	Edit Mode Step
Signup	Step 5	Step 7
Login	Step 6	Step 8

Existing Configuration Flow

If you’ve previously authenticated, the CLI detects your saved credentials on startup.

Confirmation Prompt

Existing configuration found:
URL: https://defdrive.example.com
Username: johndoe

Do you want to proceed with this? (yes/no):
|

Type 'yes' - Use existing config

Proceeding with existing configuration...
Welcome to DefDrive CLI! Configuration complete. Press q to quit.

You skip authentication entirely and can immediately use the CLI with stored credentials.

Type 'no' - Reset configuration

Resetting configuration. Please enter the URL.
Enter the URL where DefDrive is hosted:
|

The CLI clears stored credentials and starts from the beginning.

Input Controls

During any text input field, you can use:

Key	Action
Letters/Numbers	Type characters
Backspace	Delete character before cursor
←	Move cursor left
→	Move cursor right
Enter	Confirm input and continue
q or Ctrl+C	Quit CLI

The cursor is shown as | in the input field:

john|doe

Error Handling

The CLI handles various error scenarios:

Password Mismatch (Signup)

Server Connection Failure

If the CLI can’t reach the DefDrive server:

Signup failed: failed to connect to server: [error details]

Login failed: failed to connect to server: [error details]

Verify:

The URL is correct
The server is running
Network connectivity

Authentication Rejected

If the server rejects your credentials:

Signup failed: [server error message]

Login failed: [server error message]

The server’s error message is displayed. Common issues:

Username already taken (signup)
Invalid credentials (login)
Email format invalid (signup)

Invalid Response Format

If the server returns an unexpected response:

Login failed: failed to parse response: [error details]

This indicates a server-side issue or API version mismatch.

Complete Flow Diagram

[Start CLI]
    |
    v
[Load Config] ───> Config exists? ───yes──> [Confirm existing config]
    |                                              |            |
    no                                           yes          no
    |                                              |            |
    v                                              v            v
[Enter URL] ───> [Save URL]                   [Done]      [Reset]
    |                                                            |
    v                                                            |
[Auth Menu] <────────────────────────────────────────────────-+
    |
    +──> Signup ──> [Enter: name, email, username, password, confirm_password]
    |                   |
    |                   v
    |               [Review details]
    |                   |
    |                   +──> confirm ──> [Validate passwords]
    |                   |                     |
    |                   |                   match? ──yes──> [POST /api/signup]
    |                   |                     |                    |
    |                   |                     no                 success?
    |                   |                     |                    |
    |                   |                     v                  yes  no
    |                   |               [Re-enter password]       |    |
    |                   |                                         v    v
    |                   +──> edit ──> [Modify all fields] ──> [Done] [Error]
    |                                       |
    |                                       v
    |                                 [Review details]
    |
    +──> Login ──> [Enter: username, password]
                       |
                       v
                   [Review details]
                       |
                       +──> confirm ──> [POST /api/login]
                       |                     |
                       |                   success?
                       |                     |  \
                       |                   yes  no
                       |                     |   |
                       |                     v   v
                       +──> edit ──> [Done] [Error]
                                       |
                                       v
                                 [Review details]

Authentication Source Code

Key functions in cli/main.go:

func signup(url, name, email, username, password string) (string, error) {
    requestBody := fmt.Sprintf(`{
        "name": "%s",
        "email": "%s",
        "username": "%s",
        "password": "%s"
    }`, name, email, username, password)

    resp, err := http.Post(url+"/api/signup", "application/json", strings.NewReader(requestBody))
    if err != nil {
        return "", fmt.Errorf("failed to connect to server: %v", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        body, _ := ioutil.ReadAll(resp.Body)
        return "", fmt.Errorf("signup failed: %s", string(body))
    }

    // Automatically login after signup
    return login(url, username, password)
}

Security Considerations

Important Security Notes:

Password Visibility: Passwords are displayed as plain text during input in the TUI. Consider implementing masked input for production use.
Token Storage: Authentication tokens are stored in plain text in .defdrive_credentials. Restrict file permissions:
```
chmod 600 .defdrive_credentials
```
HTTPS Required: Always use HTTPS URLs for production DefDrive instances to encrypt credentials in transit.
Credential File: Add .defdrive_credentials to .gitignore to avoid committing tokens to version control.

Overview

Usage

CLI Authentication

Authentication Menu

Step 2: Enter Account Details

Step 3: Review and Confirm

Step 2: Enter Credentials

Step 3: Review and Confirm

Edit Mode Details

How Edit Mode Works

Edit Mode Flow States

Existing Configuration Flow

Confirmation Prompt

Input Controls

Error Handling

Complete Flow Diagram

Authentication Source Code

Security Considerations

Next Steps

Configuration

Introduction

Build docs developers (and LLMs) love

Overview

Usage

​Authentication Menu

​Signup Flow

​Step 1: Select Signup

​Step 2: Enter Account Details

​Step 3: Review and Confirm

​Signup API Request

​Login Flow

​Step 1: Select Login

​Step 2: Enter Credentials

​Step 3: Review and Confirm

​Login API Request

​Edit Mode Details

​How Edit Mode Works

​Edit Mode Flow States

​Existing Configuration Flow

​Confirmation Prompt

​Input Controls

​Error Handling

​Complete Flow Diagram

​Authentication Source Code

​Security Considerations

​Next Steps

Configuration

Introduction

Build docs developers (and LLMs) love

Authentication Menu

Signup Flow

Step 1: Select Signup

Step 2: Enter Account Details

Step 3: Review and Confirm

Signup API Request

Login Flow

Step 1: Select Login

Step 2: Enter Credentials

Step 3: Review and Confirm

Login API Request

Edit Mode Details

How Edit Mode Works

Edit Mode Flow States

Existing Configuration Flow

Confirmation Prompt

Input Controls

Error Handling

Complete Flow Diagram

Authentication Source Code

Security Considerations

Next Steps