Skip to main content

CLI Configuration & Precedence

The CLI manages local configuration profiles and stored credentials securely on disk.

1. On-Disk Configuration Storage​

Configuration profiles are stored in an atomically managed JSON file:

  • Windows: %APPDATA%\liorans3\config.json
    (e.g., C:\Users\<username>\AppData\Roaming\liorans3\config.json)
  • Linux & macOS: $XDG_CONFIG_HOME/liorans3/config.json or ~/.config/liorans3/config.json

File Security & Atomic Writes​

  • On POSIX systems, config.json is created with restricted owner permissions (chmod 0o600).
  • Writes are executed atomically using unique temporary staging files and fsync before file replacement, preventing corruption during system crashes.

2. Interactive Setup (liorans3 configure)​

Run liorans3 configure to launch the interactive setup wizard:

liorans3 configure

Interactive Walkthrough​

=== Configuring Lioran S3 Profile: [default] ===

? Server Endpoint URI: http://127.0.0.1:27118
? Authentication Method: Basic Authentication (Username & Password)
? Username: admin
? Password: [hidden]
? Request Timeout (ms): 30000

Verifying connection to http://127.0.0.1:27118...
Connection verified: Server status 'ok', version '0.1.0'.
Profile 'default' configured and active.

Non-Interactive Setup​

In scripts or automated environments, pass flags directly:

# Basic Authentication
liorans3 configure --profile prod --endpoint https://s3.example.com --username admin -P "MySecurePassword123!" --non-interactive

# Access Key Authentication
liorans3 configure --profile ci --endpoint https://s3.example.com --access-key bk_live_0192a7b8 --secret-key sk_live_9f83a21b --non-interactive

3. Environment Variables​

The CLI reads the following environment variables:

VariableDescription
LIORANS3_URIFull connection URI (e.g. bastion://admin:pass@127.0.0.1:27118).
LIORANS3_ENDPOINTServer endpoint URL (e.g. https://s3.example.com).
LIORANS3_USERNAMEUsername for Basic authentication.
LIORANS3_PASSWORDPassword for Basic authentication.
LIORANS3_ACCESS_KEYProgrammatic Access Key ID (bk_...).
LIORANS3_SECRET_KEYProgrammatic Access Key Secret (sk_...).
LIORANS3_PROFILENamed configuration profile to select.
BASTION_URILegacy fallback connection URI.

4. 4-Level Credential Precedence Engine​

When executing any command, liorans3 resolves connection parameters and credentials following a strict 4-level hierarchy:

Level 1: Explicit Command-Line Flags
         (-e, -u, -P, -k, -s, -p)
                 │
                 ▼ (if not specified)
Level 2: Environment Variables
         (LIORANS3_URI, LIORANS3_ENDPOINT, LIORANS3_*, BASTION_URI)
                 │
                 ▼ (if not specified)
Level 3: Explicit Profile Selection
         (--profile <name> or LIORANS3_PROFILE)
                 │
                 ▼ (if not specified)
Level 4: Default Profile from Local Configuration File

:::caution Ambiguity Detection If you pass both username/password and accessKey/secretKey simultaneously via command-line flags or environment variables, the CLI halts immediately with an InvalidInputError to prevent ambiguous authentication attempts. :::