CLI Spec

Overview

The Model Bundling Service provides a command-line interface for the LEAP (Liquid Edge AI Platform) bundling service. It allows you to upload model directories, create bundle requests, monitor processing status, and download completed bundles.

Requirements

Before using the Model Bundle Tool, ensure your system meets the following requirements:

• Python 3.8 or higher: The CLI tool is built with Python and requires at least version 3.8.
• pip installed: You need pip to install the CLI tool and its dependencies.
• AWS services access: Model uploads use Amazon Web Services (AWS) for file storage. Ensure you can access amazonaws.com domains from your network. If you’re behind a corporate firewall or VPN, you may need to configure network settings to allow access to AWS services.

Global Options

All commands support these global options:

• --version, -v: Show version information and exit
• --help: Show help information for any command

Authentication Commands

login

Authenticate with the LEAP platform using your API token.

leap-bundle login <api-token>

Arguments

• api-token (required): Your LEAP platform API token

Behavior

• Validates the API token with the LEAP platform
• Stores the token in ~/.liquid-leap configuration file
• If already logged in with a different token, prompts for confirmation to switch
• If already logged in with the same token, shows a warning message

Examples

# Login with API token
leap-bundle login leap_1234567890abcdef
 
# Example output on success
ℹ Validating API token...
✓ Successfully logged in to LEAP platform!
 
# Example output when already logged in with different token
⚠ You are already logged in with a different API token.
Do you want to log out and log in with the new token? [y/N]: y
ℹ Validating API token...
✓ Successfully logged in to LEAP platform!

Error Cases

• Invalid API token: Shows validation error and exits with code 1
• Network connectivity issues: Shows connection error
• Token storage failure: Shows file system error

logout

Clear stored authentication credentials.

leap-bundle logout

Arguments: None

Behavior

• Removes the stored API token from the configuration file
• If not logged in, shows informational message
• Always exits successfully

Examples

# Logout from LEAP platform
leap-bundle logout
 
# Example output on success
✓ Successfully logged out from LEAP platform!
 
# Example output when not logged in
ℹ You are not currently logged in.

whoami

Display information about the currently authenticated user.

leap-bundle whoami

Arguments: None

Behavior

• Queries the LEAP platform API to get user information
• Displays the email address associated with the current API token
• Requires valid authentication

Examples

# Check current user
leap-bundle whoami
 
# Example output on success
✓ Logged in as: user@example.com
 
# Example output when not logged in
✗ You are not logged in. Run 'leap-bundle login' first.

Error Cases

• Not authenticated: Prompts to login first
• Invalid/expired token: Shows authentication error
• Network issues: Shows connection error

Configuration Commands

config

View CLI configuration settings.

leap-bundle config

Behavior

• Displays current configuration and config file location
• Configuration is stored in ~/.liquid-leap

Examples

# View current configuration
leap-bundle config
 
# Example output
ℹ Config file location: /home/user/.liquid-leap
 
Current configuration:
  server_url: https://leap.liquid.ai

Bundle Management Commands

create

Create a new bundle request by uploading a model directory.

leap-bundle create <input-path>

Arguments

• input-path (required): Path to the directory to upload and bundle

Options

• --dry-run: Validate the input directory without actually creating a request or uploading files.
• --json: Output result in JSON format for programmatic parsing.
• --parallel: Upload files in parallel with multipart support. This is the default behavior if neither --parallel nor --sequential is specified.
• --sequential: Upload files sequentially. This is the fallback option if parallel upload fails.
  • If neither --parallel nor --sequential is specified, the CLI will attempt parallel upload first, and fall back to sequential if it fails.
  • If both --parallel and --sequential are specified, --parallel takes precedence.

Behavior

• Calculates a hash of the directory contents
• Creates a bundle request on the LEAP platform
• Uploads the directory contents to cloud storage
• Updates the request status throughout the process
• If a request with the same hash already exists, shows a warning instead of creating a duplicate

Examples

# Create bundle from directory
leap-bundle create ./my-model-directory
 
# Example output on success
ℹ Calculating directory hash...
ℹ Submitting bundle request...
✓ Bundle request created with ID: 18734
ℹ Starting upload...
Uploading directory... ✓
✓ Upload completed successfully! Request ID: 18734
 
# Example output when request already exists
⚠ A bundle request with the same input hash already exists: req_xyz789abc123
 
# Create bundle with JSON output
leap-bundle create ./my-model-directory --json
 
# Example JSON output on success
{"request_id": "18734", "status": "success"}
 
# Example JSON output when request already exists
{"error": "A bundle request with the same input hash already exists: req_xyz789abc123", "status": "exists"}

Validation

• Hidden files and subdirectories (starting with .) are ignored
• The directory must have a valid config.json file
• The directory must have one or more safe tensor files with the .safetensors extension
• Individual files must not exceed 10GB
• The total size of the directory must not exceed 10GB
  • This limit will be increased in the future as the bundle service supports more models

Error Cases

• Directory doesn’t exist: Shows file not found error
• Path is not a directory: Shows invalid path error
• Not authenticated: Prompts to login first
• Upload failure: Shows upload error and updates request status to failed
  • Upload will timeout in 10 minutes if not completed. We are working on optimizing upload performance.
  • For transient issues, try resuming the upload: leap-bundle resume <request-id>
  • For persistent issues, cancel the request and create a new one
• Network issues: Shows connection error

Process Flow

1. Validates input directory exists
2. Calculates directory hash for deduplication
3. Creates bundle request via API
4. Uploads directory contents to S3 using signed URLs
5. Updates request status to track progress

Rate Limits

Processing Time

If the request is not rate limited, it will usually be completed within 20 minutes for small model checkpoints.

resume

Resume uploading for a failed or interrupted bundle request.

leap-bundle resume [<request-id>]

Arguments

• request-id (optional): ID of the bundle request to resume. If not provided, resumes the latest request.

Options

• --json: Output result in JSON format for programmatic parsing
• --sequential: Upload files sequentially (fallback option if parallel upload fails)
• --parallel: Upload files in parallel with multipart support (default behavior if neither option is specified)

Behavior

• Retrieves the specified bundle request (or latest request if no ID provided)
• Validates that the request is in a resumable status (“Uploading” or “Uploading Failed”)
• Checks that the original input directory still exists
• Resumes the upload process from where it left off
• Updates the request status throughout the process
• Supports both parallel and sequential upload mechanisms

Examples

# Resume the latest failed upload
leap-bundle resume
 
# Example output on success
ℹ Retrieving latest bundle request...
✓ Resuming upload for request 18734...
ℹ Input path: /path/to/model/directory
ℹ Using parallel upload with multipart support...
✓ Upload completed successfully! Request ID: 18734
 
# Resume a specific request by ID
leap-bundle resume 18734
 
# Example output
ℹ Retrieving bundle request 18734...
✓ Resuming upload for request 18734...
ℹ Input path: /path/to/model/directory
ℹ Using parallel upload with multipart support...
✓ Upload completed successfully! Request ID: 18734
 
# Resume with JSON output
leap-bundle resume 18734 --json
 
# Example JSON output on success
{"request_id": "18734", "status": "success"}
 
# Example JSON output on error
{"error": "Resume only works for model uploading. Current status: completed"}

Resumable Statuses

The resume command only works for requests in the following statuses:

• Uploading: Upload was interrupted before the status was updated
• Uploading Failed: Upload encountered an error

Upload Mechanisms

• Parallel (default): Uses multipart upload with better performance for large files
• Sequential: Uploads files one by one, used as fallback if parallel upload fails
• If parallel upload fails, the command automatically falls back to sequential upload
• You can force sequential upload using the --sequential flag

Error Cases

• Not authenticated: Prompts to login first
• Request not found: Shows request not found error
• Request not resumable: Shows status error (only “Uploading” and “Uploading Failed” requests can be resumed)
• Original directory missing: Shows directory not found error
• Upload failure: Shows upload error and updates request status
• Network issues: Shows connection error

validate

Validate a directory for bundle creation without uploading or creating a request. This command is equivalent to the create command with --dry-run option, but does not require authentication.

leap-bundle validate <input-path>

Arguments

• input-path (required): Path to the directory to validate

Behavior

• Performs the same validation checks as the create command
• Does not require authentication
• Does not upload files or create bundle requests
• Useful for checking if a directory is ready for bundling before actually creating a request

Examples

# Validate a model directory
leap-bundle validate ./my-model-directory
 
# Example output on success
✓ Directory validation passed
✓ Directory is ready for bundle creation
 
# Example output on failure
✗ Validation failed: No config.json found in directory.

Validation

The same validation rules apply as for the create command:

• Hidden files and subdirectories (starting with .) are ignored
• The directory must have a valid config.json file
• The directory must have one or more safe tensor files with the .safetensors extension
• Individual files must not exceed 10GB
• The total size of the directory must not exceed 10GB

Error Cases

• Directory doesn’t exist: Shows file not found error
• Path is not a directory: Shows invalid path error
• Validation failure: Shows specific validation error message

list

List bundle requests or get details for a specific request.

leap-bundle list [<request-id>]

Arguments

• request-id (optional): Specific request ID to get detailed information

Options

• --json: Output result in JSON format for programmatic parsing
• --last: Show only the most recent request

Behavior

• Without arguments: Lists 50 most recent bundle requests
• With request ID: Shows detailed information for the specific request
• With --last: Shows only the most recent request
• Displays requests in a formatted table (unless --json is used)
• JSON output available for both list and specific request queries

Examples

# List all requests
leap-bundle list
 
# Example output
Bundle Requests (50 most recent)
┏━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ID    ┃ Input Path               ┃ Status     ┃ Creation             ┃ Notes                       ┃
┡━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 18734 │ /path/to/model/directory │ completed  │ 2024-01-15T10:30:00Z │ Processing completed.       │
│ 18733 │ /path/to/other/directory │ processing │ 2024-01-15T09:15:00Z │ Request is being processed. │
└───────┴──────────────────────────┴────────────┴──────────────────────┴─────────────────────────────┘
✓ Found 2 bundle requests.
 
# Get details for specific request
leap-bundle list 18734
 
# Example output
✓ Request Details:
  ID:         18734
  Input Path: /path/to/model/directory
  Status:     completed
  Creation:   2024-01-15T10:30:00Z
  Update:     2024-01-15T10:45:00Z
  Notes:      Processing completed. Run "leap-bundle download 18734" to download the bundle.
 
# Get details with JSON output
leap-bundle list 18734 --json
 
# Example JSON output
{
  "request_id": "18734",
  "input_path": "/path/to/model/directory",
  "status": "completed",
  "created_at": "2024-01-15T10:30:00Z",
  "user_message": "Processing completed. Run \"leap-bundle download 18734\" to download the bundle."
}
 
# List all requests with JSON output
leap-bundle list --json
 
# Example JSON output
{
  "requests": [
    {
      "request_id": "18734",
      "input_path": "/path/to/model/directory",
      "status": "completed",
      "created_at": "2024-01-15T10:30:00Z",
      "user_message": "Processing completed."
    },
    {
      "request_id": "18733",
      "input_path": "/path/to/other/directory",
      "status": "processing",
      "created_at": "2024-01-15T09:15:00Z",
      "user_message": "Request is being processed."
    }
  ]
}
 
# Show only the most recent request
leap-bundle list --last
 
# Example output
Most Recent Bundle Request
┏━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ID    ┃ Input Path               ┃ Status     ┃ Creation             ┃ Notes                       ┃
┡━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 18734 │ /path/to/model/directory │ completed  │ 2024-01-15T10:30:00Z │ Processing completed.       │
└───────┴──────────────────────────┴────────────┴──────────────────────┴─────────────────────────────┘
✓ Found 1 bundle request.
 
# Show most recent request with JSON output
leap-bundle list --last --json
 
# Example JSON output
{
  "requests": [
    {
      "request_id": "18734",
      "input_path": "/path/to/model/directory",
      "status": "completed",
      "created_at": "2024-01-15T10:30:00Z",
      "user_message": "Processing completed."
    }
  ]
}

Request Statuses

• New: The request is newly created
• Uploading: The model files are being uploaded
• Uploading Failed: The upload encountered an error
• Processing: The bundle is being processed
• Processing Failed: Processing failed
• Completed: The request is successfully completed and ready for download
• Cancelled: The request is cancelled by the user
• Archived: The request is archived and no longer available for download; this happens automatically 5 days after completion

Error Cases

• Not authenticated: Prompts to login first
• Request ID not found: Shows not found error
• Network issues: Shows connection error

download

Download the bundle file for a completed request.

leap-bundle download <request-id> [--output-path <path>]

Arguments

• request-id (required): ID of the bundle request to download

Options

• --output-path <path>: Directory to save the downloaded file (default: current directory)

Behavior

• Requests a signed download URL from the LEAP platform
• Downloads the bundle file using the signed URL
• Saves the file with a default name or to the specified output path

Examples

# Download to current directory
leap-bundle download 18734
 
# Example output
ℹ Requesting download for bundle request 18734...
✓ Download URL obtained for request 18734
Downloading bundle output... ✓
✓ Download completed successfully! File saved to: input-8da4w_output_8da8w-seq_8196.bundle
 
# Download to specific directory
leap-bundle download 18734 --output-path ./downloads/
 
# Example output
ℹ Requesting download for bundle request 18734...
✓ Download URL obtained for request 18734
Downloading bundle output... ✓
✓ Download completed successfully! File saved to: downloads/input-8da4w_output_8da8w-seq_8196.bundle

Error Cases

• Request not found: Shows request not found error
• Request not completed: Shows status error (request must be in “completed” status)
• Request already archived: Shows archived error
• Output directory doesn’t exist: Shows directory not found error
• Output path is not a directory: Shows invalid path error
• Download failure: Shows network or file system error
• Not authenticated: Prompts to login first

cancel

Cancel a bundle request that is still processing.

leap-bundle cancel <request-id>

Arguments

• request-id (required): ID of the bundle request to cancel

Behavior

• Sends a cancellation request to the LEAP platform
• Updates the request status to “cancelled”
• Cannot cancel requests that are already completed or archived

Examples

# Cancel a processing request
leap-bundle cancel 18734
 
# Example output on success
ℹ Cancelling bundle request 18734...
✓ Request cancelled successfully.
 
# Example output when request is already completed
ℹ Cancelling bundle request 18734...
✓ Request was already completed and cannot be cancelled.

Error Cases

• Request not found: Shows request not found error
• Request already completed: Shows informational message
• Not authenticated: Prompts to login first
• Network issues: Shows connection error

Configuration File

The CLI tool stores configuration in ~/.liquid-leap as a YAML file:

version: 1
api_token: 'your_encrypted_token_here'
server_url: 'https://leap.liquid.ai'

Location: The file is always stored in the user’s home directory as .liquid-leap.

Current Limitations

• The bundle tool only works on these model types for now: LFM2, LFM2-VL, Qwen.
  • We are working on expanding support to more models.x

Error Handling

Authentication Errors

# Example authentication error
✗ You must be logged in. Run 'leap-bundle login' first.
 
# Example invalid token error
✗ Invalid API token. Please check your token and try again.

Network Errors

# Example connection error
✗ Failed to connect to server: Connection timeout
 
# Example API error
✗ HTTP 429 error: Rate limit exceeded. Please try again later.

File System Errors

# Example directory not found
✗ Directory does not exist: /path/to/nonexistent/directory
 
# Example permission error
✗ Failed to save login credentials: Permission denied

API Response Errors

The CLI tool extracts and displays error messages from API responses:

# Example API error response
✗ Bundle processing failed: Insufficient disk space on server

Exit Codes

The CLI tool uses standard exit codes:

• 0: Success
• 1: General error (authentication, network, file system, etc.)