Milesoft CLI Command Reference (milesoft-cli)

This document provides a comprehensive explanation of all commands and options available in the milesoft Command Line Interface.

Installation

Download and install the native binary automatically using the universal installer script (supports macOS, Linux, and WSL):

curl -fsSL https://milesoft.io/cli/install.sh | sh

1. Global Flags

These flags are persistent and can be applied to any top-level command or subcommand:

Flag Type Description Default Environment Variable
--config string Path to the config file $HOME/.config/milesoft/config.yaml -
--field string Display only the requested field from get commands - -
--json bool Output formatted raw JSON schema false -
--limit int Pagination limit for listing results 50 -
--cursor string Pagination cursor for listing results "" -
-y, --yes bool Bypass prompt confirmations and auto-approve false -

2. Command Hierarchy

Below is the directory structure of the milesoft command tree:

3. Command Reference

3.1 Core Architecture & Secure Operations

The CLI is engineered around security, seamless session persistence, and token-efficient programmatic communication.

Dual-Mode Architecture

  • CLI Mode: Offers highly organized terminal layouts, formatting, and tables for manual developer workflows.
  • MCP Mode (milesoft mcp): Launches an active stdio-based JSON-RPC 2.0 server. Highly automated AI agents can connect and invoke platform tools directly without human intervention.

Secure Keyring Authentication

  • OAuth with PKCE: Securely authenticates using proof key extensions (PKCE) over terminal/browser handshakes. Prompts for verification securely and supports Multi-Factor Authentication (MFA) codes.
  • Keyring/Keychain Storage: Instead of saving high-risk Refresh Tokens in plain text configuration files, the CLI stores them securely in the native OS Keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service via DBus) using the zalando/go-keyring library.
  • Access Token Cache: Caches short-lived, low-risk JWT Access Tokens locally in ~/.config/milesoft/session.json with strict 0600 file permissions.

Silent Refresh Middleware

  • Transparent Token Management: Features custom middleware via an http.RoundTripper (pkg/auth/SilentRefreshRoundTripper).
  • When an API request is made, the middleware automatically inspects the local token expiration time. If expired or expiring within 1 minute, it seamlessly retrieves the Refresh Token from the OS Keyring, calls the central gateway to refresh the session, saves the new tokens, and appends the fresh bearer authorization to the outgoing request. No manual refresh commands are ever needed.

milesoft login

Authenticates securely with the Milesoft Platform using administrative super credentials. This command initiates an interactive multi-step login flow that securely prompts for your email, password, MFA method, and MFA verification code.

Interactive Walkthrough

  1. Email Prompt: Prompts for your login email. If a default email is configured in ~/.config/milesoft/config.yaml, it will be shown in brackets (e.g., (default: admin@milesoft.io)). Pressing Enter automatically accepts the default.
  2. MFA Method Prompt: Prompts for your preferred MFA method (Email or Phone). Defaults to Email (or whatever is stored in your configuration).
  3. Password Entry: Prompts for your password.

    • Interactive Terminal (TTY): Input is securely masked while typing using the native terminal library, ensuring shoulder-surfing protection.

    • Piped/Script Input (Non-TTY): Supports reading plain-text passwords directly from standard input streams (e.g., echo "mypassword" | milesoft login), making it suitable for automated scripting.

      ⚠️ Security Tip: To avoid leaking passwords into your shell history, read from a secure environment variable or use a hidden input stream instead of echoing passwords directly in plaintext: milesoft login < password.txt.

  4. App Context Multi-App Selection (Optional): If the administrator account is linked to multiple active applications, the CLI displays a list of available apps and prompts the user to select one:
    Multiple apps found. Please select an app:
[1] Main Developer Suite (ID: app-123)
[2] Customer Portal (ID: app-456)
Select an app [1-2]:
    Selecting an option automatically re-submits the login context for that specific application.
  5. MFA Verification Code: Triggers an MFA code delivery via your chosen method and prompts for the verification code:
    An MFA verification code has been sent via Email to ad***@milesoft.io.
Enter MFA Verification Code:

Output Actions & Persistence

Upon successful authentication, the CLI performs the following background actions:

  • Obtains short-lived JWT Access Tokens and persistent Refresh Tokens from the platform gateway.
  • Securely persists the tokens: short-lived access tokens are cached in ~/.config/milesoft/session.json with strict 0600 read-write permissions, while refresh tokens are stored securely in the native OS Keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service).
  • Automatically creates or updates your local configuration at ~/.config/milesoft/config.yaml to save your email and MFA method preferences, allowing for ultra-fast, single-key subsequent login attempts.

Usage

milesoft login [flags]

Examples

Single-App Interactive Login
$ milesoft login
=========================================================
             Milesoft Platform Super Login
=========================================================
Enter Email (default: admin@milesoft.io): admin@milesoft.io
Enter MFA Method (Email or Phone) [default: Email]: Email
Enter Password: 

Authenticating administrative credentials with platform gateway...

An MFA verification code has been sent via Email to ad***@milesoft.io.
Enter MFA Verification Code: 123456

Saved login profile defaults to ~/.config/milesoft/config.yaml.

Success! Secure session established. Welcome to the Milesoft CLI!
Multi-App Selection Interactive Login
$ milesoft login
=========================================================
             Milesoft Platform Super Login
=========================================================
Enter Email: super-admin@milesoft.io
Enter MFA Method (Email or Phone) [default: Email]: Email
Enter Password: 

Authenticating administrative credentials with platform gateway...

Multiple apps found. Please select an app:
[1] Internal Admin Panel (ID: app-987)
[2] Client Workspace (ID: app-654)
Select an app [1-2]: 2

Authenticating administrative credentials with platform gateway...

An MFA verification code has been sent via Email to su***@milesoft.io.
Enter MFA Verification Code: 987654

Saved login profile defaults to ~/.config/milesoft/config.yaml.

Success! Secure session established. Welcome to the Milesoft CLI!

milesoft whoami

Queries the platform to confirm the active application ID, account ID, user ID, email, and security roles.

Output Modes

  • TTY Interactive Mode: When running in an active terminal session, the CLI formats the session information inside an elegant, human-readable ASCII card.
  • JSON Schema Mode (Pipes & Scripts): When stdout is piped or redirected, or when the --json flag is supplied, the command automatically falls back to printing structural, formatting-stable raw JSON. This ensures zero parsing friction for downstream shell scripts or automated AI tools.

Usage

milesoft whoami [flags]

Examples

Standard TTY Card Output
$ milesoft whoami
=========================================================================
             Active Milesoft Session Context
=========================================================================
Email:          admin@milesoft.io
User ID:        user-4455-abc
App ID:         app-123-prod
Account ID:     acc-9988-xyz
Roles:          ROLE_SUPER
=========================================================================
Automated JSON Output (or Piped/Redirected)
$ milesoft whoami --json

JSON Schema Result:

{
  "appId": "app-123-prod",
  "accountId": "acc-9988-xyz",
  "userId": "user-4455-abc",
  "email": "admin@milesoft.io",
  "roles": [
    "ROLE_SUPER"
  ]
}

milesoft mcp

Launches the Model Context Protocol (MCP) JSON-RPC server over stdio, enabling automated AI assistants like Gemini CLI or Claude Code to securely interact with the Milesoft Platform.

Usage

milesoft mcp [flags]

milesoft version

Print detailed client version, build commit, build date, Go runtime version, and local operating system / architecture environment details.

Version Invocation Alternatives

  1. Subcommand: milesoft version prints exhaustive multi-line build details.
  2. Global Flags: Calling milesoft --version or milesoft -v prints a simplified, single-line version identifier.

Usage

milesoft version [flags]

Examples

Exhaustive Subcommand Version Output
$ milesoft version
Client Version: 0.0.3
Commit:         b6f5d8a87612c3e1e90e764a8fc3de3b7301c23a
Build Date:     2026-07-17
Go Version:     go1.21.5
OS/Arch:        darwin/arm64
Single-line Root Version Output
$ milesoft --version
Milesoft CLI version 0.0.3

milesoft update

Queries our public Google Cloud Storage registry to compare local build metadata against the latest published release. If a newer release is detected, the command downloads and runs the universal installer script automatically to update your local installation.

Update Check & Installation Flow

  1. Query Latest Release: Makes a lightweight GET request to the public registry metadata endpoint: https://storage.googleapis.com/milesoft-cli-releases/latest.txt.
  2. Compare Local Version: Normalizes and compares the cleaned version strings (ignoring any leading 'v').
  3. Execution Context:
    • If Up to Date: Prints a status message and exits without any network pull or file writes.
    • If New Version Available: Displays the upgrade notification (e.g. A new version of Milesoft CLI is available: v0.0.5 (current: v0.0.4)), downloads the universal installer script from https://storage.googleapis.com/milesoft-cli-releases/install.sh, and pipes it directly into the system shell to execute the binary upgrade in place.

Usage

milesoft update [flags]

Examples

Already Up to Date Context
$ milesoft update
Milesoft CLI is already up to date (current version: v0.0.4).
Upgrade Action Context
$ milesoft update
A new version of Milesoft CLI is available: v0.0.5 (current: v0.0.4)
Downloading and running the universal installer...
Installing Milesoft CLI...
Successfully upgraded to v0.0.5!