OmegaSafe CLI

The CLI documentation below reflects the current OmegaSafe CLI commands, configuration, and encrypted-file behavior. The published command name is omegasafe.

Read Quick Start before this document for the quickest path to start encrypting and decrypting files; this page is the comprehensive reference for all OmegaSafe CLI commands and configuration options.

1. Download And Access

#

The current download and access flow is:

1. Sign in to OmegaSafe Cloud.
2. Open Download in the signed-in navigation.
3. Select CLI.
4. Choose a platform tile for the binary, or select Source Code for the source package.
5. Create an API key in OmegaSafe Cloud before configuring HTTP ECS. See Quick Start — 2. Generate an API Key.
6. Run omegasafe init without extra arguments for the simplified interactive setup flow. See OmegaSafe CLI — init for a full reference on the command and available arguments.

For direct source code package integrations, see OmegaSafe CLI — Source Code integrations.

2. Configuration Root And Init

#

The default configuration directory is:

• ~/.omegasafe on Linux and macOS
• %LOCALAPPDATA%\omegasafe on Windows

Every CLI command supports path override with -d, --config-dir. For init --config-dir, the directory must already exist. If --config-dir is omitted, the default OS location is used and directory is created automatically.

When designing automation, pass --config-dir on every command for deterministic behavior.

omegasafe init creates:

All three containers are protected by the resolved configuration password.

3. Configuration Password

#

On the first omegasafe init in a fresh environment, when OMEGASAFE_CONFIG_PASSWORD is not set, OmegaSafe CLI generates a strong random configuration password and stores it in the system keyring automatically. Subsequent commands read that keyring entry without any additional setup. The password can be overridden or set manually via the OMEGASAFE_CONFIG_PASSWORD environment variable.

On later init runs without OMEGASAFE_CONFIG_PASSWORD, if an existing password is found in the keyring, OmegaSafe CLI either reuses it (when --reuse-password argument is passed, or when omitted, when reuse is selected during interactive prompt) or generates a new strong random password (when --new-password argument is passed, or when omitted, when new password is selected during interactive prompt). When OMEGASAFE_CONFIG_PASSWORD is set, these flags do not change password selection.

Purpose and protection

#

The configuration password protects the three local SecureFileContainer files created by init: omegasafe_keys.sfc, local_cache.sfc, and ecs_storage.sfc. These containers are encrypted with AES-256-GCM. A container copied to a different device without the matching password is locked out and unreadable — the password is required to open it.

For the container format details, see Encryption Method — Secure File Container.

Resolution order

#

1. OMEGASAFE_CONFIG_PASSWORD environment variable (highest priority; keyring is bypassed when set).
2. Keyring entry (looked up by keyring service/secret labels, defaults: service omegasafe, secret OMEGASAFE_CONFIG_PASSWORD).
3. If neither exists, commands fail and require init or environment setup.

Keyring record labels can be overridden with OMEGASAFE_KEYRING_SERVICE_NAME and OMEGASAFE_KEYRING_SECRET_NAME environment variables. These are environment-variable overrides only — they are not properties in config.ini and cannot be set through omegasafe set-config. Defaults: service label omegasafe, secret label OMEGASAFE_CONFIG_PASSWORD. Use both overrides when you need isolated profiles on one machine (for example, separate CI and local identities); keep the same pair of values across all commands in that profile.

Setting up OmegaSafe CLI on a new device

#

Because the local containers are encrypted with the configuration password, you cannot simply copy them to a new device and expect them to work without also transferring the password. The recommended path avoids dealing with the password entirely:

1. On the new device, run omegasafe init — this generates a fresh configuration password and empty containers.
2. Recreate or migrate your ECS connection first: either run omegasafe create-http-ecs to register a new connection, or use omegasafe export-ecs on the old device and omegasafe import-ecs on the new one. ECS must be set up before importing keys, because import-key requires an ECS UUID.
3. Export each Alpha key on the old device with omegasafe export-key and import it on the new device with omegasafe import-key --ecs-uuid YOUR_ECS_UUID.

This approach keeps each device’s configuration password independent and avoids the risk of password synchronisation errors. Manually transferring or recreating the configuration password is possible but not recommended.

4. Full config.ini Structure

#

config.ini has four sections:

• [Global settings - static]
• [Global settings - dynamic]
• [OmegaSafe encryption keys]
• [OmegaSafe encrypted files]

Static Properties

#

Section: [Global settings - static]

These values are loaded and cached for process lifetime; CLI process restart is required to reliably pick up manual edits. Currently, the CLI commands are independent and short lived. But in the future when daemon process is introduced, the restart requirement will matter more.

• KEYS_CONTAINER_PATH — default: <config_root>/omegasafe_keys.sfc
• LOCAL_CACHE_CONTAINER_PATH — default: <config_root>/local_cache.sfc
• ECS_CONTAINER_PATH — default: <config_root>/ecs_storage.sfc

Dynamic Properties

#

Section: [Global settings - dynamic]

• OFFLINE_MODE (TRUE/FALSE, default FALSE) — governs claim flow for encryption/import workflows that need to claim global positions. FALSE: if local PERFORMANCE cache cannot satisfy a request, OmegaSafe CLI may call ECS to refill PERFORMANCE/OFFLINE cache claims. TRUE: ECS claim path is intentionally skipped for those requests, and OmegaSafe CLI attempts OFFLINE cache fallback instead. Local PERFORMANCE cache is still used first when available; OFFLINE_MODE mainly changes behavior when external refill would otherwise be needed. Also disables the software update check path.
• UPDATE_CHECK (TRUE/FALSE, default TRUE) — governs the post-command CLI update check. FALSE: skip remote CLI version checks. TRUE: update check is allowed, but still skipped if OFFLINE_MODE=TRUE or no HTTP ECS is available.
• ECS_UUID_DEFAULT (UUID or empty) — mainly needed when multiple ECS entries are configured: for commands that allow omitting --ecs-uuid (notably create-key), OmegaSafe CLI uses the only configured ECS automatically, but requires a default or explicit --ecs-uuid when multiple ECS entries exist. Also used by list-ecs to mark default ECS and by update-check logic to prefer that ECS. Empty value means “no default”.
• CACHE_OFFLINE_KEY_CAPACITY_GB (number in range 0..1000, default 10) — target OFFLINE cache top-up size used by claimant refill logic. Unit is decimal GB (1 GB = 1,000,000,000 bytes); fractional values are allowed. Effective refill size is safety-capped to 25% of current key capacity. 0 disables OFFLINE top-up targeting (existing OFFLINE claims can still be consumed).
• CACHE_PERFORMANCE_KEY_CAPACITY_GB (number in range 0..1000, default 10) — PERFORMANCE cache refill chunk size used for fast local sub-claims during encryption flows. Unit is decimal GB (1 GB = 1,000,000,000 bytes); fractional values are allowed. Effective refill size is safety-capped to 25% of current key capacity. 0 disables PERFORMANCE refill behavior; claims use direct ECS path (or OFFLINE fallback when ECS is unavailable).

Section: [OmegaSafe encrypted files]

• TRADITIONAL_ENC_LAYER_PASS (string or empty) — governs optional second-layer password protection for encrypted file containers (encrypt/decrypt) and encrypted delta containers. Empty means no traditional layer. Non-empty means the same password must be present in all environments that need to read/write those encrypted containers. See Encryption Method — Optional Traditional Encryption Layer. This property does not control config-container passwording (omegasafe_keys.sfc, local_cache.sfc, ecs_storage.sfc); those use the OmegaSafe CLI — Configuration Password source.

Section: [OmegaSafe encryption keys]

• Currently no active properties.

How Dynamic Properties Are Changed

#

omegasafe set-config supports: OFFLINE_MODE, UPDATE_CHECK, TRADITIONAL_ENC_LAYER_PASS, ECS_UUID_DEFAULT (including clear), CACHE_OFFLINE_KEY_CAPACITY_GB, and CACHE_PERFORMANCE_KEY_CAPACITY_GB.

• Boolean arguments accept: 1, true, yes, on, 0, false, no, off.
• --traditional-enc-layer-pass validates basic complexity: minimum 8 chars, at least one letter, at least one digit, no whitespace.
• Cache-capacity arguments use the same numeric constraints as config parsing: decimal number in range 0..1000 (fractional values allowed).

5. Environment Overrides And Config Resolution Order

#

Supported dynamic environment overrides:

• OMEGASAFE_OFFLINE_MODE → OFFLINE_MODE
• OMEGASAFE_UPDATE_CHECK → UPDATE_CHECK
• OMEGASAFE_ECS_UUID_DEFAULT → ECS_UUID_DEFAULT
• OMEGASAFE_CACHE_OFFLINE_KEY_CAPACITY_GB → CACHE_OFFLINE_KEY_CAPACITY_GB
• OMEGASAFE_CACHE_PERFORMANCE_KEY_CAPACITY_GB → CACHE_PERFORMANCE_KEY_CAPACITY_GB
• OMEGASAFE_TRADITIONAL_ENC_LAYER_PASS → TRADITIONAL_ENC_LAYER_PASS

Boolean environment values accepted by resolver: truthy: 1, true, yes, on; falsy: 0, false, no, off. Invalid values are ignored with a warning, then resolver falls back to config.ini or defaults.

Config-root environment override: OMEGASAFE_CONFIG_DIR.

Config resolution order for file location: --config-dir argument → OMEGASAFE_CONFIG_DIR → OS default path.

In automation, pass --config-dir on every command for deterministic behavior.

6. set-config And Dynamic Settings

#

Update runtime/dynamic configuration values with omegasafe set-config. All dynamic properties settable via omegasafe set-config and their environment override counterparts:

Traditional Encryption Layer

#

Use the optional traditional encryption layer when you want the outer SecureFileContainer to be password-protected with AES-256-GCM.

Configure it in any of these ways:

• Set TRADITIONAL_ENC_LAYER_PASS in config.ini.
• Set OMEGASAFE_TRADITIONAL_ENC_LAYER_PASS as an environment-variable override.
• Run omegasafe set-config --traditional-enc-layer-pass <TRADITIONAL_ENC_LAYER_PASS> to update TRADITIONAL_ENC_LAYER_PASS in config.ini.

To disable the layer, clear the config.ini value with omegasafe set-config --traditional-enc-layer-pass "" or remove TRADITIONAL_ENC_LAYER_PASS from config.ini. If OMEGASAFE_TRADITIONAL_ENC_LAYER_PASS is set, it overrides config.ini, so you must unset or remove that environment variable as well.

For the full feature documentation see Encryption Method — Optional Traditional Encryption Layer.

7. Output And Logging Conventions

#

• User-facing command output is printed to stdout.
• Diagnostic and error details are produced through logging.
• All commands support -h, --help and -l, --log-level <LOG_LEVEL>.
• The top-level omegasafe command also supports -V, --version to show the installed OmegaSafe CLI version and exit.
• Valid named log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL, NOTSET. There is no named OFF level. Numeric levels are accepted; --log-level 100 effectively suppresses logger output.

Stream split:

• DEBUG and INFO logs go to stdout.
• WARNING and above go to stderr.

Clean JSON Output Guidance

#

If you need machine-only JSON on stdout:

• Use the command --json mode where supported.
• Set --log-level WARNING (or stricter).
• Disable update-check prints (they are stdout prints, not logs):

omegasafe set-config --update-check false

Structured Output (--json)

#

The following commands support structured output with -j, --json:

• list-ecs
• list-keys
• view-key
• key-storage-limits
• list-ecs-storages
• view-ecs-storage

Conventions for those commands:

• JSON mode and plain mode represent the same data.
• None is rendered as null.
• Booleans are rendered as true/false.
• The payload root includes schema_version for compatibility tracking.

8. Command Reference

#

All commands accept -d, --config-dir <CONFIG_DIR> to use a non-default configuration root. Use the same directory consistently across your isolated setups so keys, cache, ECS links, and dynamic settings stay aligned.

The top-level version check is omegasafe -V or omegasafe --version; it prints the installed OmegaSafe CLI version and exits.

init

#

Initialize local OmegaSafe configuration, containers, and optionally an HTTP ECS connection. Provide no arguments for fully interactive setup.

See OmegaSafe CLI — Configuration Root And Init for the default config-root location and created files, and OmegaSafe CLI — Configuration Password for password resolution and keyring behavior.

Arguments

• -c, --create-http-ecs (Optional): Create HTTP ECS during init by CLI arguments (requires --http-ecs-name, --http-ecs-url, --http-ecs-api-key). If not provided, user will be prompted for these details, unless --skip-http-ecs is passed.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory (must be reused on later commands for that config set).
• -h, --help (Optional): Show command help.
• -k, --http-ecs-api-key <HTTP_ECS_API_KEY> (Optional): HTTP ECS API key. Must be generated on the HTTP ECS portal.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.
• -n, --http-ecs-name <HTTP_ECS_NAME> (Optional): HTTP ECS display name for non-interactive setup.
• -o, --override-existing (Optional): Overwrite existing configuration without prompt.
• -p, --new-password (Optional): Generate a new config password (existing encrypted containers become inaccessible).
• -r, --reuse-password (Optional): Reuse existing keyring password without prompt.
• -s, --skip-http-ecs (Optional): Skip HTTP ECS setup prompt.
• -u, --http-ecs-url <HTTP_ECS_URL> (Optional): HTTP ECS base URL (host[:port][/base], no scheme).
• -v, --http-ecs-dev-mode (Optional): Enable HTTP ECS development mode (skip certificate verification).
• -x, --no-override (Optional): Refuse to overwrite existing configuration.

Detailed behavior

• This command is the entry point for first-time setup.
• Creates config file plus default local containers (keys, cache, ECS connection container).
• Stores or reuses config password in OS keyring unless password is provided via environment variable.
• If config already exists, prints existing path and asks for confirmation. Depending on the prompt choice or override argument, cancels or performs destructive re-init.
• Can immediately register an HTTP ECS connection for online key claims and Delta sync.
• On success, prints initialization summary including configuration directory and next-step guidance.
• Interactive mode may print prompt validation, cancellation, and guidance messages.

encrypt

#

Encrypt a file with a selected key UUID. All claiming, caching, and key maintenance is automated. May need to connect to ECS if local cache does not have a sufficient claim.

Arguments

• -i, --input-file <FILE_PATH> (Mandatory): Path to plaintext file to encrypt.
• -k, --key-uuid <KEY_UUID> (Mandatory): Key UUID to use.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -f, --file-name-override <FILE_NAME_OVERRIDE> (Optional): Output filename override.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.
• -o, --output-dir <OUTPUT_DIR> (Optional): Directory for encrypted output file.
• -t, --max-threads <MAX_THREADS> (Optional): Worker/thread limit.

Detailed behavior

• Resolves local key/cache/ECS context, then runs encryption and claim workflow.
• Output filename defaults to random UUID with .omegasafe extension when not overridden.
• Writes encrypted output as a SecureFileContainer payload; see Encryption Method — Outer Structure: SecureFileContainer for format details.
• If optional traditional encryption layer (TRADITIONAL_ENC_LAYER_PASS / OMEGASAFE_TRADITIONAL_ENC_LAYER_PASS) is enabled, the decrypting side must be configured with the same password.
• Prints output path and performance summary.
• May trigger a key renewal/new Delta generation if the latest Delta ran out of capacity.
• Claiming and cache behavior follow the model in the OmegaSafe CLI — Claiming System section below.
• Success output includes: File encrypted successfully: <output_path>.

decrypt

#

Decrypt an OmegaSafe encrypted file. Uses encryption metadata embedded in the encrypted file. Does not require connection to ECS, unless the key Delta used for encrypting the file was generated on a different device and was not pulled to this device yet.

Arguments

• -i, --input-file <FILE_PATH> (Mandatory): Path to encrypted file.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -f, --file-name-override <FILE_NAME_OVERRIDE> (Optional): Decrypted filename override. If not provided, original filename is restored.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.
• -o, --output-dir <OUTPUT_DIR> (Optional): Directory for decrypted output file.
• -t, --max-threads <MAX_THREADS> (Optional): Worker/thread limit.

Detailed behavior

• Reads encryption metadata to resolve key_uuid, then requires matching local key material.
• Uses local cache and ECS linkage to resolve needed Delta/key state.
• If encrypted files were produced with optional traditional layer password protection, decryption requires the same configured password (TRADITIONAL_ENC_LAYER_PASS / OMEGASAFE_TRADITIONAL_ENC_LAYER_PASS).
• Prints output path and performance summary.
• If required local key (Alpha) is missing, command fails with an actionable import-key message.
• Success output includes: File decrypted successfully: <output_path>.

set-config

#

Update runtime/dynamic configuration values used by CLI flows.

Arguments

• -c, --clear-ecs-uuid-default (Optional): Clear default ECS UUID.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -e, --ecs-uuid-default <ECS_UUID_DEFAULT> (Optional): Set default ECS UUID.
• -f, --cache-offline-key-capacity-gb <CACHE_OFFLINE_KEY_CAPACITY_GB> (Optional): Set offline cache target in GB.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.
• -o, --offline-mode <OFFLINE_MODE> (Optional): Set OFFLINE_MODE (true/false).
• -p, --cache-performance-key-capacity-gb <CACHE_PERFORMANCE_KEY_CAPACITY_GB> (Optional): Set performance cache target in GB.
• -t, --traditional-enc-layer-pass <TRADITIONAL_ENC_LAYER_PASS> (Optional): Set or clear ("") the config.ini TRADITIONAL_ENC_LAYER_PASS value. Unset OMEGASAFE_TRADITIONAL_ENC_LAYER_PASS separately if that override is in use.
• -u, --update-check <UPDATE_CHECK> (Optional): Set UPDATE_CHECK (true/false).

Detailed behavior

• Applies only provided dynamic values; leaves others unchanged.
• If no changes are provided, prints No configuration changes requested.
• Otherwise, prints one summary line describing effective updates.
• OFFLINE_MODE, cache capacities, and default ECS directly influence claim path and command defaults.
• Claim/capacity behavior is described in the OmegaSafe CLI — Claiming System section below.

erase-all

#

Permanently remove local OmegaSafe config, containers, and stored keyring password. Fully offline. Does not affect ECS.

Arguments

• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -f, --force (Optional): Skip destructive confirmation prompts.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• Deletes config directory and default container artifacts.
• Also removes configured custom container paths that are outside config directory.
• Attempts to remove the stored config password from keyring.
• This is a destructive operation and cannot be undone.
• Prints destructive warning text and affected paths before confirmation flow.
• Without --force, may print Operation aborted..
• On success, prints removed paths and keyring-password removal status.
• erase-all removes local resources only and does not call ECS delete APIs. For HTTP ECS, remote keys/deltas are preserved. For local SFC ECS, the ECS is a local file; if that file is under the config directory it is removed by erase-all.

create-key

#

Create a new Alpha key, register it in ECS, and generate/upload the first Delta. Skip optional arguments to use interactive setup (recommended).

Arguments

• -c, --number-of-rotors <NUMBER_OF_ROTORS> (Optional): Number of rotors.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -e, --ecs-uuid <ECS_UUID> (Optional): Target ECS UUID. If omitted, create-key uses ECS_UUID_DEFAULT when set, otherwise the only configured ECS.
• -h, --help (Optional): Show command help.
• -k, --key-name <KEY_NAME> (Optional): Key display name.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.
• -n, --nucleus-size-mb <NUCLEUS_SIZE_MB> (Optional): Nucleus size in MB.
• -r, --rotor-size-mb <ROTOR_SIZE_MB> (Optional): Rotor size in MB.
• -s, --storage-uuid <STORAGE_UUID> (Optional): Storage UUID for HTTP ECS Delta uploads. Use OmegaSafe CLI — list-ecs-storages to inspect available storage UUIDs.
• -w, --max-workers <MAX_WORKERS> (Optional): Worker limit for key generation.

Detailed behavior

• Creates local Alpha key iteration and matching local cache entry.
• Registers key metadata in ECS and uploads first Delta as encrypted payload.
• HTTP ECS Delta uploads are limited to 10 MiB for internal and BYOS storage. OmegaSafe CLI calculates the encrypted Delta’s MD5 locally, submits its exact size and Base64 digest, validates the returned signed size, checksum, and upload-attempt headers, and transfers the file directly to S3 or R2. If storage returns 412 Precondition Failed, OmegaSafe CLI confirms with the returned upload-attempt UUID so only the matching existing object can be accepted. See Bring Your Own Storage — Delta Upload Safeguards.
• Resolves the target ECS in this order: --ecs-uuid, then ECS_UUID_DEFAULT, then the only configured ECS. If multiple ECS entries exist and no default is configured, the command stops and requires explicit selection.
• For HTTP ECS, resolves target storage in this order: --storage-uuid when provided, otherwise the only available storage, otherwise interactive selection. If no BYOS storage has been created on that HTTP ECS yet, the only available storage is OmegaSafe Internal Storage, so it is selected automatically. To use BYOS for the new key, create the storage first with OmegaSafe CLI — create-ecs-storage, then provide --storage-uuid or select it when prompted.
• If a stage fails, command attempts cleanup of previously created artifacts.
• Prints selected ECS/storage context and selected key profile/capacity summary.
• On success, prints Alpha key summary and first-Delta summary.
• Interactive mode may print prompt validation and selection guidance.

Interactive configuration prompt

When run interactively, create-key presents a key profile selection with four presets:

For each preset, the following capacity summary fields are shown to the user:

CUSTOM option valid ranges:

• Nucleus size: 0.10 MB – 1.00 MB
• Rotor size: 0.10 MB – 1.00 MB
• Number of rotors: 2 – 4

Capacity guidance table:

Capacity of a single key iteration for the given size and rotor-count combination.

Notes shown during interactive selection:

1. MEDIUM/RECOMMENDED is the default preset and is suitable for most use cases.
2. Use BYOS (Bring Your Own Storage) rather than internal storage for production keys. Cloudflare R2 offers a generous free tier that is well beyond typical OmegaSafe usage needs. See Bring Your Own Storage — Recommendation.
3. Larger keys provide more capacity but take longer to generate and consume more disk space.
4. Key size cannot be changed after creation; create a new key if you need a different size.

list-keys

#

List locally actionable keys with capacity, Delta, and ECS-status summary.

Arguments

• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -j, --json (Optional): Emit structured JSON payload.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• Includes only keys that have local Alpha presence (locally actionable keys).
• Keys that exist only on ECS (without local Alpha) are intentionally hidden.
• Merges local key/cache state with ECS-derived status where available.
• key_name_local always comes from local Alpha metadata and remains deterministic.
• key_name_ecs comes from ECS and is null when ECS key data is unavailable.
• external_claims_storage_status reports availability class (available, authentication error, unreachable, unavailable, not configured).
• deltas_keys_size_on_disk is intentionally estimated as one_local_delta_raw_size * latest_local_delta_sequence. This estimate is expected to scale with sequence count.

Structured payload

• root:
  • schema_version (integer)
  • keys (array)
• keys[] object:
  • key_name_local (string)
  • key_name_ecs (string or null)
  • key_uuid (UUID string)
  • alpha_key_size_on_disk (object; expected present for listed keys):
    • bytes (integer)
    • display (string)
  • alpha_capacity_left (object; expected present for listed keys):
    • remaining_bytes (integer)
    • total_bytes (integer)
    • percent_remaining (number)
    • display (string)
  • minimum_number_of_deltas (integer; expected present for listed keys)
  • total_key_encryption_capacity_left (object or null):
    • remaining_bytes (integer)
    • total_bytes (integer)
    • percent_remaining (number)
    • display (string)
  • maximum_file_size_for_encryption (object; expected present for listed keys):
    • bytes (integer)
    • display (string)
  • deltas_keys_size_on_disk (object or null):
    • bytes (integer)
    • display (string)
  • latest_delta_uuid (UUID string or null)
  • latest_delta_sequence (integer or null)
  • latest_delta_capacity_left (object or null):
    • remaining_bytes (integer)
    • total_bytes (integer)
    • percent_remaining (number)
    • display (string)
  • external_claims_storage_name (string or null)
  • external_claims_storage_uuid (UUID string or null)
  • external_claims_storage_status (string enum: available, authentication error, unreachable, unavailable, not configured)

Nullability notes:

• key_name_local is expected to be present for listed keys because local Alpha is required.
• key_name_ecs is null when ECS key data is unavailable.
• alpha_* size/capacity fields and maximum_file_size_for_encryption are expected to be present for actionable keys (local Alpha exists).
• deltas_keys_size_on_disk is null when no local Delta exists yet.
• total_key_encryption_capacity_left and latest_delta_capacity_left are null when ECS Delta data is unavailable (for example ECS unreachable/authentication error).
• latest_delta_uuid and latest_delta_sequence are null only when neither local nor ECS Delta data is available.

{
  "schema_version": 1,
  "keys": [
    {
      "key_name_local": "Finance-Key",
      "key_name_ecs": "Finance-Key",
      "key_uuid": "11111111-2222-4333-8444-555555555555",
      "alpha_key_size_on_disk": {
        "bytes": 52428800,
        "display": "50.0 MB"
      },
      "alpha_capacity_left": {
        "remaining_bytes": 838860800,
        "total_bytes": 1073741824,
        "percent_remaining": 78.1,
        "display": "78.1% 800.0 MB (838,860,800 bytes)"
      },
      "minimum_number_of_deltas": 102,
      "total_key_encryption_capacity_left": {
        "remaining_bytes": 4026531840,
        "total_bytes": 5368709120,
        "percent_remaining": 75.0,
        "display": "75.0% 3.8 GB (4,026,531,840 bytes)"
      },
      "maximum_file_size_for_encryption": {
        "bytes": 1073741824,
        "display": "1.0 GB (1,073,741,824 bytes)"
      },
      "deltas_keys_size_on_disk": {
        "bytes": 104857600,
        "display": "100.0 MB"
      },
      "latest_delta_uuid": "66666666-7777-4888-8999-aaaaaaaaaaaa",
      "latest_delta_sequence": 2,
      "latest_delta_capacity_left": {
        "remaining_bytes": 734003200,
        "total_bytes": 1073741824,
        "percent_remaining": 68.3,
        "display": "68.3% 700.0 MB (734,003,200 bytes)"
      },
      "external_claims_storage_name": "prod-http-ecs",
      "external_claims_storage_uuid": "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff",
      "external_claims_storage_status": "available"
    }
  ]
}

view-key

#

Show detailed state for one locally actionable key across local key data, cache data, and ECS data.

Arguments

• -k, --key-uuid <KEY_UUID> (Mandatory): Key UUID to inspect.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -j, --json (Optional): Emit structured JSON payload.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• Requires local Alpha presence for the key UUID.
• Resolves ECS from local cache linkage, then attempts ECS metadata and Delta reads.
• key_summary.key_name_local and local_key_data.key_name come from local Alpha metadata and stay stable.
• key_summary.key_name_ecs and ecs_key_data.key_name come from ECS metadata and become null when ECS key data is unavailable.
• Returns partial output when ECS is unavailable instead of hard-failing; ECS-related fields become null/empty and status reflects availability class.
• In partial output mode, local sections remain populated from local key/cache sources.
• external_claims_storage_name is best-effort when ECS is unavailable (from local ECS metadata if available).
• Typical warning logs include:
  • ExternalClaimsStorage <ecs_uuid> unavailable (...); result is partial.
  • Key <key_uuid> missing data from ExternalClaimsStorage; result is partial.
• In partial output mode, notable affected fields are:
  • key_summary.external_claims_storage_status becomes one of authentication error, unreachable, unavailable
  • key_summary.key_name_ecs is null
  • key_summary.latest_delta_capacity_left is null
  • key_summary.total_key_encryption_capacity_left is null
  • ecs_key_data.* fields are null
  • deltas is []
• Performs local/ECS Delta-sequence conflict detection and fails fast on conflict. Conflicts are not expected in normally operating system.
• Missing local Alpha fails with actionable import-key guidance.

Structured payload

• root:
  • schema_version (integer)
  • key_summary (object) — same shape and nullability rules as one list-keys item
  • ecs_key_data (object)
  • local_key_data (object)
  • local_cache_data (object)
  • deltas (array)
• ecs_key_data:
  • key_uuid (UUID string or null)
  • key_name (string or null)
  • storage_uuid (string or null)
  • storage_name (string or null)
  • storage_is_internal (boolean or null)
  • omegasafe_version (string or null)
  • alpha_global_position_capacity (integer, string, or null)
  • alpha_latest_claimed_global_position (integer, string, or null)
  • key_role_id (integer or null)
  • key_role_name (string or null)
  • user_key_relation_uuid (UUID string or null)
  • billing_user_uuid (UUID string or null)
  • billing_user_email (string or null)
  • billing_exp_ts (integer or null)
  • billing_exp_datetime (ISO 8601 UTC string or null)
  • billing_expired (boolean or null)
  • is_billing_user (boolean or null)
• local_key_data:
  • key_name (string; immutable local Alpha name)
  • key_uuid (UUID string)
  • omegasafe_version (string)
  • key_capacity (integer)
  • start_global_position (integer)
  • end_global_position (integer)
  • alpha_iteration_uuid (UUID string)
  • alpha_iteration_sequence (integer, expected 0)
  • latest_iteration_uuid (UUID string)
  • latest_iteration_sequence (integer)
  • latest_delta_iteration_uuid (UUID string or null)
  • latest_delta_iteration_sequence (integer or null)
  • iterations_count (integer)
• local_cache_data:
  • key_uuid (UUID string)
  • key_iteration_uuid (UUID string)
  • ecs_uuid (UUID string)
  • local_claims_count (integer)
  • local_claims_by_reason (object map of reason → integer count)
  • performance_capacity_left (object or null):
    • remaining_bytes (integer)
    • total_bytes (integer)
    • percent_remaining (number)
    • display (string)
  • offline_capacity_left (object or null):
    • remaining_bytes (integer)
    • total_bytes (integer)
    • percent_remaining (number)
    • display (string)
• deltas[]:
  • seq_number (integer)
  • delta_uuid (UUID string)
  • start_global_position (integer)
  • end_global_position (integer)
  • latest_claimed_global_position (integer)

Nullability notes:

• If ECS is unavailable/unreachable/authentication-failed, ecs_key_data.* becomes null, deltas is [], and ECS-derived fields in key_summary become null.
• local_key_data remains populated for actionable keys.
• latest_delta_iteration_* in local_key_data can be null when no local Delta exists.
• performance_capacity_left and offline_capacity_left are null when no local claims exist for that reason.

{
  "schema_version": 1,
  "key_summary": {
    "key_name_local": "Finance-Key",
    "key_name_ecs": "Finance-Key",
    "key_uuid": "11111111-2222-4333-8444-555555555555",
    "alpha_key_size_on_disk": { "bytes": 52428800, "display": "50.0 MB" },
    "alpha_capacity_left": {
      "remaining_bytes": 838860800, "total_bytes": 1073741824,
      "percent_remaining": 78.1, "display": "78.1% 800.0 MB (838,860,800 bytes)"
    },
    "minimum_number_of_deltas": 102,
    "total_key_encryption_capacity_left": {
      "remaining_bytes": 4026531840, "total_bytes": 5368709120,
      "percent_remaining": 75.0, "display": "75.0% 3.8 GB (4,026,531,840 bytes)"
    },
    "maximum_file_size_for_encryption": { "bytes": 1073741824, "display": "1.0 GB (1,073,741,824 bytes)" },
    "deltas_keys_size_on_disk": { "bytes": 104857600, "display": "100.0 MB" },
    "latest_delta_uuid": "66666666-7777-4888-8999-aaaaaaaaaaaa",
    "latest_delta_sequence": 2,
    "latest_delta_capacity_left": {
      "remaining_bytes": 734003200, "total_bytes": 1073741824,
      "percent_remaining": 68.3, "display": "68.3% 700.0 MB (734,003,200 bytes)"
    },
    "external_claims_storage_name": "prod-http-ecs",
    "external_claims_storage_uuid": "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff",
    "external_claims_storage_status": "available"
  },
  "ecs_key_data": {
    "key_uuid": "11111111-2222-4333-8444-555555555555",
    "key_name": "Finance-Key",
    "storage_uuid": "12345678-90ab-4cde-8f01-234567890abc",
    "storage_name": "r2-primary",
    "storage_is_internal": false,
    "omegasafe_version": "1.7.0",
    "alpha_global_position_capacity": 1073741824,
    "alpha_latest_claimed_global_position": 209715199,
    "key_role_id": 1,
    "key_role_name": "Owner",
    "user_key_relation_uuid": "0a0a0a0a-1b1b-4c4c-8d8d-9e9e9e9e9e9e",
    "billing_user_uuid": "2f2f2f2f-3a3a-4b4b-8c8c-1d1d1d1d1d1d",
    "billing_user_email": "owner@example.com",
    "billing_exp_ts": 1772457600,
    "billing_exp_datetime": "2026-03-02T00:00:00+00:00",
    "billing_expired": false,
    "is_billing_user": true
  },
  "local_key_data": {
    "key_name": "Finance-Key",
    "key_uuid": "11111111-2222-4333-8444-555555555555",
    "omegasafe_version": "1.7.0",
    "key_capacity": 1073741824,
    "start_global_position": 0,
    "end_global_position": 1073741823,
    "alpha_iteration_uuid": "12121212-2222-4333-8444-555555555555",
    "alpha_iteration_sequence": 0,
    "latest_iteration_uuid": "66666666-7777-4888-8999-aaaaaaaaaaaa",
    "latest_iteration_sequence": 2,
    "latest_delta_iteration_uuid": "66666666-7777-4888-8999-aaaaaaaaaaaa",
    "latest_delta_iteration_sequence": 2,
    "iterations_count": 3
  },
  "local_cache_data": {
    "key_uuid": "11111111-2222-4333-8444-555555555555",
    "key_iteration_uuid": "66666666-7777-4888-8999-aaaaaaaaaaaa",
    "ecs_uuid": "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff",
    "local_claims_count": 3,
    "local_claims_by_reason": { "performance": 2, "offline": 1 },
    "performance_capacity_left": {
      "remaining_bytes": 157286400, "total_bytes": 209715200,
      "percent_remaining": 75.0, "display": "75.0% 150.0 MB (157,286,400 bytes)"
    },
    "offline_capacity_left": {
      "remaining_bytes": 52428800, "total_bytes": 104857600,
      "percent_remaining": 50.0, "display": "50.0% 50.0 MB (52,428,800 bytes)"
    }
  },
  "deltas": [
    {
      "seq_number": 2,
      "delta_uuid": "66666666-7777-4888-8999-aaaaaaaaaaaa",
      "start_global_position": 1073741824,
      "end_global_position": 2147483647,
      "latest_claimed_global_position": 1413480447
    }
  ]
}

edit-key

#

Edit key metadata in HTTP ECS for a locally actionable key.

Arguments

• -k, --key-uuid <KEY_UUID> (Mandatory): Key UUID to edit.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -f, --force (Optional): Skip the confirmation prompt when changing a key from OmegaSafe Internal Storage (Bring Your Own Storage — Internal Storage Limits) to BYOS (Bring Your Own Storage — Editing Storage Settings).
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.
• -n, --key-name <KEY_NAME> (Optional): New ECS key name.
• -s, --storage-uuid <STORAGE_UUID> (Optional): New storage UUID association.
• -v, --omegasafe-version <OMEGASAFE_VERSION> (Optional): New version metadata value. Debug only. Do not change unless you know what you are doing.

Detailed behavior

• Requires local Alpha to ensure key is actionable in CLI.
• Missing local Alpha fails with the same actionable import-key guidance used by view-key.
• Resolves ECS context from local cache and applies metadata update through HTTP ECS API.
• Changing storage_uuid requires OWNER permission on that key; MAINTAINER can edit name and omegasafe_version but cannot reassign storage. See Keys Management — Storage Ownership Model.
• key_uuid is immutable.
• edit-key with --key-name updates the ECS key name in HTTP ECS; it does not edit the local Alpha metadata.
• CLI reads immutable local Alpha name in key_name_local / local_key_data.key_name and exposes the ECS key name separately in key_name_ecs / ecs_key_data.key_name.
• When changing a key from OmegaSafe Internal Storage (Bring Your Own Storage — Internal Storage Limits) to BYOS (Bring Your Own Storage — Editing Storage Settings), the CLI warns that OmegaSafe does not move Delta files and asks for confirmation unless --force is used.
• Before confirming that Internal-to-BYOS storage change, download the existing Deltas from the web UI (Keys → Deltas → Download per Delta) or through POST /deltas/download_url, then place them in the target storage at {remote_path}/{key_uuid}/{delta_uuid} or {key_uuid}/{delta_uuid} when remote_path is empty.
• The warning also reminds that switching the key back to OmegaSafe Internal Storage (see Keys Management — Storage Ownership Model) is not supported by the API.
• Prints backend result text returned by ECS key edit operation.

delete-key

#

Delete a key from ECS when reachable, attempt to remove its Delta files from the linked storage, and always clean up the local key and cache entries.

Arguments

• -k, --key-uuid <KEY_UUID> (Mandatory): Key UUID to delete.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -f, --force (Optional): Skip confirmation prompt.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• Requires local Alpha to treat key as actionable.
• Missing local Alpha fails with the same actionable import-key guidance used by view-key.
• Prompts for confirmation unless --force is used.
• Attempts ECS-side delete using resolved ECS backend type.
• Attempts Delta files deletion from the storage linked to ECS.
• If the confirmation prompt is declined, prints Deletion aborted. and exits without deleting anything.
• Continues local cleanup even if ECS delete is unavailable/fails.
• On completion, prints Delete-key completed for key <uuid>.
• Detailed ECS/local deletion and partial-failure diagnostics are logged.
• delete-key is failure-isolated: if ECS lookup/removal is unavailable, local key iterations and local cache entries are still removed.

export-key

#

Export the local Alpha iteration for a given key UUID. Needed when following Keys Management — Key Sharing Model and Keys Management — Alpha Distribution Requirement to share a key with other users and devices.

Arguments

• -k, --key-uuid <KEY_UUID> (Mandatory): Key UUID whose Alpha should be exported.
• -o, --output-path <OUTPUT_PATH> (Mandatory): Destination file path.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• Finds the key’s Alpha iteration (seq_number == 0) and exports it.
• Output is intended for secure transfer/backup workflows.
• Treat exported Alpha as highly sensitive material; possession enables decryption for that key UUID.
• The Alpha key itself will not be possible to use for decrypting any files without access to Deltas. Do not share credentials; use sharing features in ECS.
• On success, prints export destination and Alpha identifiers.
• For the full Alpha/Delta security and sharing model, see Encryption Method — Alpha and Delta Split.

import-key

#

Import an Alpha key file to complete Keys Management — Key Sharing Model and Keys Management — Alpha Distribution Requirement, bind it to ECS context, then reconcile missing Deltas and initialize cache claims.

Arguments

• -e, --ecs-uuid <ECS_UUID> (Mandatory): ECS where the key must already be registered. Can be provided from list-ecs command. If the ECS is not configured locally yet, create it first with OmegaSafe CLI — create-http-ecs for HTTP ECS or OmegaSafe CLI — create-sfc-ecs for SFC ECS.
• -i, --input-file <FILE_PATH> (Mandatory): Path to exported Alpha key file.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• Imports Alpha iteration into local key container and writes local cache linkage.
• Verifies key registration in target ECS.
• Runs a small encryption flow to trigger missing-Delta pull and initial claim-cache setup.
• Prints claim-summary message by reason when available.
• Prints selected ECS context and key import status lines.
• On success, prints imported Alpha summary fields.

import-key-delta

#

Manually import one encrypted Delta payload into local key storage.

WARNING: This is a manual recovery path intended for situations where ECS is unavailable and the user has access to trusted Delta files (for example via Bring Your Own Storage). It bypasses ECS authority checks. If a non-authoritative Delta is imported, local state can diverge from ECS (different UUID for the same Delta seq_number) and manual recovery will be required. Once ECS is reachable, divergence is detected by commands that compare local and ECS Delta sequence mappings, including view-key, pull-missing-deltas, and encrypt when it enters the ECS claim path.

Arguments

• -i, --input-file <FILE_PATH> (Mandatory): Encrypted Delta container file.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -f, --force (Optional): Skip manual-import warning confirmation.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• This is a recovery/manual workflow; normal Delta sync is automatic.
• Requires local Alpha and cache-resolved ECS linkage for the key UUID in the Delta metadata.
• Decrypts the container with local Alpha and validates the decrypted payload (key_uuid match and key_iteration_seq_number > 0).
• Enforces local sequence continuity for manual import: if the incoming Delta UUID is not already present locally, its sequence must be exactly the next local sequence (latest + 1).
• If the exact same Delta iteration UUID already exists locally, the import is skipped as already present.
• Divergence can happen if this command manually imports one Delta for sequence N while another device or user has already created and uploaded a different Delta UUID for that same sequence N; once ECS is reachable again, that same-sequence UUID mismatch is treated as divergence and requires manual recovery.
• This command does not verify that incoming Delta UUID for a sequence matches authoritative ECS mapping for that sequence; importing wrong Delta can introduce local/ECS same-sequence UUID divergence.
• Ensures local cache entry exists for imported Delta.
• Without --force, the CLI prints the manual-import warning, then shows the interactive prompt Do you want to continue with manual Delta import? [y/N]:. If the prompt is declined, it prints Operation aborted. and exits without importing anything.
• On success, prints whether Delta was imported or already present, then prints key/delta UUID, sequence, and global-position range fields.
• Fails when local Alpha is missing, local ECS-link context is missing, decrypted payload is not a Delta, or sequence continuity validation fails.

pull-missing-deltas

#

Proactively reconcile and pull ECS Deltas that are missing locally for one key UUID.

Arguments

• -k, --key-uuid <KEY_UUID> (Mandatory): Key UUID to reconcile.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• Requires local actionable key context.
• Useful for proactive synchronization; normal encrypt/decrypt/import-key flows already reconcile when needed.
• Lists ECS Deltas, compares with local Delta UUIDs, downloads/imports missing items in sequence order.
• Performs local/ECS same-sequence conflict detection and stops on mismatch.
• On no-op, prints: No missing deltas found for key_uuid=<uuid>.
• On pull, prints missing count, one line per imported/skipped Delta, and completion summary (imported, skipped).
• Fails if ECS is unavailable.

key-storage-limits

#

Fetch internal storage usage/limit metrics for a key on HTTP ECS. Applicable only to keys that are not using user-provided storage (Bring Your Own Storage — Internal Storage Limits).

Arguments

• -k, --key-uuid <KEY_UUID> (Mandatory): Key UUID to query.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -j, --json (Optional): Emit structured JSON payload.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• Requires local actionable key context and resolves ECS from local cache state.
• Missing local Alpha fails with the same actionable import-key guidance used by view-key.
• Works for HTTP ECS path (uses backend limits endpoint).
• Returns structured usage map for upload/download scopes when available.
• message is an optional backend informational text, typically used when usage metrics are not provided (for example when key uses user-provided storage).
• usage may be null if backend does not return limits payload.

Structured payload

• root:
  • schema_version (integer)
  • ecs_uuid (UUID string)
  • ecs_name (string or null)
  • key_uuid (UUID string)
  • message (string or null; informational reason when usage is absent)
  • usage (object or null)
• usage:
  • uploads (object map: scope name → metric object)
  • downloads (object map: scope name → metric object)
• metric object:
  • used (integer, number, or null)
  • limit (integer, number, or null)
  • remaining (integer, number, or null)
  • percentage (integer, number, or null)
  • has_limit (boolean or null)

Default HTTP ECS per-key limits:

• uploads: daily=2, monthly=5, stored=15
• downloads: daily=20, monthly=200

{
  "schema_version": 1,
  "ecs_uuid": "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff",
  "ecs_name": "prod-http-ecs",
  "key_uuid": "11111111-2222-4333-8444-555555555555",
  "message": null,
  "usage": {
    "uploads": {
      "daily": { "used": 1, "limit": 2, "remaining": 1, "percentage": 50, "has_limit": true },
      "monthly": { "used": 2, "limit": 5, "remaining": 3, "percentage": 40, "has_limit": true },
      "stored": { "used": 3, "limit": 15, "remaining": 12, "percentage": 20, "has_limit": true }
    },
    "downloads": {
      "daily": { "used": 4, "limit": 20, "remaining": 16, "percentage": 20, "has_limit": true },
      "monthly": { "used": 11, "limit": 200, "remaining": 189, "percentage": 6, "has_limit": true }
    }
  }
}

list-ecs

#

List configured Encryption Method — External Claims Storage entries from the local ECS connection container.

Arguments

• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -j, --json (Optional): Emit structured JSON payload.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• Reads configured ECS entries and marks default ECS status.
• Includes best-effort connection metadata fields (path, url, development_mode) when available.
• Useful for selecting ECS UUIDs for create/import/edit flows.

Structured payload

• root:
  • schema_version (integer)
  • default_ecs_uuid (UUID string or null)
  • default_ecs_missing (boolean)
  • entries (array)
• entries[]:
  • ecs_name (string)
  • ecs_uuid (UUID string)
  • is_default (boolean)
  • path (string or null)
  • url (string or null)
  • development_mode (boolean or null)

{
  "schema_version": 1,
  "default_ecs_uuid": "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff",
  "default_ecs_missing": false,
  "entries": [
    {
      "ecs_name": "prod-http-ecs",
      "ecs_uuid": "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff",
      "is_default": true,
      "path": null,
      "url": "app.omega-safe.com:443",
      "development_mode": false
    },
    {
      "ecs_name": "local-sfc",
      "ecs_uuid": "99999999-aaaa-4bbb-8ccc-dddddddddddd",
      "is_default": false,
      "path": "/home/user/.omegasafe/local_claims.sfc",
      "url": null,
      "development_mode": null
    }
  ]
}

create-http-ecs

#

Create an HTTP ECS configuration entry. Skip arguments for interactive setup.

Arguments

• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -k, --api-key <API_KEY> (Optional): HTTP ECS API key.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.
• -n, --ecs-name <ECS_NAME> (Optional): HTTP ECS display name.
• -u, --api-url <API_URL> (Optional): HTTP ECS API base URL (host[:port][/base], no scheme).
• -v, --dev-mode (Optional): Enable development mode (skip certificate verification).

Detailed behavior

• Creates HTTP ECS configuration object with credentials and URL. Persists in local ECS container.
• Supports interactive setup when required values are omitted.
• This is the typical backend for online claim and Delta operations.
• On success, prints created HTTP ECS URL, UUID, and name.

create-sfc-ecs

#

Create a SFC ECS entry. Skip arguments for interactive setup.

Note: SFC ECS is local-only and not recommended for multiple devices or concurrent use.

Arguments

• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.
• -n, --ecs-name <ECS_NAME> (Optional): SFC ECS display name.
• -p, --sfc-path <SFC_PATH> (Optional): File path for SFC claims storage file.
• -x, --no-confirm-sfc-ecs (Optional): Decline SFC warning without interactive prompt.
• -y, --confirm-sfc-ecs (Optional): Accept SFC warning without interactive prompt.

Detailed behavior

• Creates a local file-based ECS backend reference and stores it in ECS container.
• Validates uniqueness of ECS name and SFC file path across existing ECS entries.
• This backend is local-only and behaves differently from HTTP ECS operational model. Not recommended for multiple devices and concurrency.
• May print Operation aborted. when user declines confirmation flow.
• On success, prints created SFC ECS path, UUID, and name.
• Interactive mode may print validation/prompt guidance.

edit-ecs

#

Edit an existing ECS entry (name plus backend-specific fields). Skip optional fields for interactive setup.

Arguments

• -e, --ecs-uuid <ECS_UUID> (Mandatory): ECS UUID to edit.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -k, --update-api-key <UPDATE_API_KEY> (Optional): Set new HTTP API key directly.
• -K, --keep-api-key (Optional): Keep existing HTTP API key without prompt.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.
• -m, --move-file (Optional): Move SFC file to new path automatically.
• -N, --keep-name (Optional): Keep existing ECS name without prompt.
• -n, --new-name <NEW_NAME> (Optional): Set new ECS name.
• -P, --keep-path (Optional): Keep existing SFC path without prompt.
• -p, --new-path <NEW_PATH> (Optional): Set new SFC path.
• -u, --new-api-url <NEW_API_URL> (Optional): Set new HTTP API base URL.
• -U, --keep-api-url (Optional): Keep existing HTTP API URL without prompt.
• -x, --no-move-file (Optional): Do not move SFC file; update reference only.

Detailed behavior

• Applies shared metadata edits (name) and type-specific edits:
  • SFC: path and optional file move.
  • HTTP: URL and optional API key update.
• HTTP API-key updates trigger connection verification; failed verification aborts and reverts key update.
• Persists updated ECS configuration object to local ECS container.
• Prints edited ECS context, applied updates, and final ECS UUID/name/type summary.
• May print API-key verification flow messages for HTTP ECS.
• Interactive mode may print validation/prompt guidance.

export-ecs

#

Export one configured ECS connection from the local ECS container. Intended for backup, migration, or simplifying setup across multiple devices for the same user.

WARNING: The exported ECS configuration object contains live connection details and is sensitive. For HTTP ECS that includes the ECS URL, API key, and development-mode setting, along with ECS metadata such as UUID, name, type, and OmegaSafe version. It is highly discouraged to share ECS export files with other users. As explained in Keys Management — Alpha Distribution Requirement, access should be granted through the invitation flow instead, so permissions stay scoped to the specific key and role, access can be revoked cleanly, and broader ECS access is not leaked during handover. Use export-ecs only for backup, migration, or multi-device setup for the same user.

Arguments

• -e, --ecs-uuid <ECS_UUID> (Mandatory): ECS UUID to export.
• -o, --output-path <OUTPUT_PATH> (Mandatory): Destination export file path.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• Validates ECS UUID exists locally, then exports connection object.
• Export payload includes the connection details needed to recreate that ECS entry.
• Prints export destination plus ECS identifiers.
• Used with import-ecs for migration/backup and same-user multi-device workflows, not for cross-user credential sharing.

import-ecs

#

Import an ECS connection export file into local ECS container.

WARNING: ECS export files contain live connection details and must be treated as sensitive secrets. For HTTP ECS this includes the ECS URL, API key, and development-mode setting. Do not share these files between different users. Use export-ecs/import-ecs only for backup, migration, or multi-device setup for the same user.

Arguments

• -i, --input-file <FILE_PATH> (Mandatory): Path to ECS export file.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• Loads ECS object from file and writes it to local ECS container.
• Prints imported UUID/name/type.
• For HTTP ECS, imported operations use the URL, API key, and development-mode setting stored in the file.
• Used to migrate connection configuration between machines/profiles for the same operator identity.
• Used with export-ecs for migration/backup and same-user multi-device workflows, not for cross-user credential sharing.

list-ecs-storages

#

List storage backends available on an ECS. For HTTP ECS, the list also includes OmegaSafe Internal Storage alongside any configured BYOS storages. This command is mostly intended for working with Bring Your Own Storage — Provider Configuration.

Arguments

• -e, --ecs-uuid <ECS_UUID> (Mandatory): ECS UUID to inspect.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -j, --json (Optional): Emit structured JSON payload.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• For HTTP ECS, lists configured storage entries with type/internal badges, including the OmegaSafe Internal Storage entry.
• For SFC ECS, returns empty storages with explanatory note.
• The root note field is produced directly by the handler for explanatory cases: non-null for SFC ECS (no per-storage listing model), non-null for HTTP ECS when no storages are configured, null when regular storage list is returned.
• Useful before create-key --storage-uuid and edit-key commands.

Structured payload

• root:
  • schema_version (integer)
  • ecs_uuid (UUID string)
  • ecs_name (string or null)
  • ecs_type (string or null)
  • storages (array)
  • note (string or null)
• storages[]:
  • storage_uuid (UUID string or null)
  • storage_name (string or null)
  • storage_is_internal (boolean or null)
  • storage_type_name (string or null)
  • storage_badge (string or null)

{
  "schema_version": 1,
  "ecs_uuid": "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff",
  "ecs_name": "prod-http-ecs",
  "ecs_type": "HTTP",
  "storages": [
    {
      "storage_uuid": "12345678-90ab-4cde-8f01-234567890abc",
      "storage_name": "r2-primary",
      "storage_is_internal": false,
      "storage_type_name": "Cloudflare R2",
      "storage_badge": "Cloudflare R2"
    },
    {
      "storage_uuid": "64753caf-2d47-4558-8933-9691b58f9b09",
      "storage_name": "OmegaSafe internal",
      "storage_is_internal": true,
      "storage_type_name": "Internal",
      "storage_badge": "internal"
    }
  ],
  "note": null
}

view-ecs-storage

#

Show more detailed information for one storage backend on an HTTP ECS. This is mostly intended for inspecting Bring Your Own Storage — Provider Configuration after identifying a storage with OmegaSafe CLI — list-ecs-storages.

Arguments

• -e, --ecs-uuid <ECS_UUID> (Mandatory): ECS UUID.
• -s, --storage-uuid <STORAGE_UUID> (Mandatory): Storage UUID.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -j, --json (Optional): Emit structured JSON payload.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• HTTP ECS only.
• Returns provider/bucket/region/endpoint/path/internal metadata for one storage.
• Used to validate storage wiring and identifiers.

Structured payload

• root:
  • schema_version (integer)
  • ecs_uuid (UUID string)
  • ecs_name (string or null)
  • ecs_type (string or null)
  • storage (object)
• storage:
  • storage_uuid (UUID string)
  • name (string or null)
  • provider (string or null)
  • bucket_name (string or null)
  • region (string or null)
  • endpoint_url (string or null)
  • storage_type_id (integer or null)
  • storage_type_name (string or null)
  • remote_path (string or null)
  • is_internal (boolean or null)

{
  "schema_version": 1,
  "ecs_uuid": "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff",
  "ecs_name": "prod-http-ecs",
  "ecs_type": "HTTP",
  "storage": {
    "storage_uuid": "12345678-90ab-4cde-8f01-234567890abc",
    "name": "r2-primary",
    "provider": "r2",
    "bucket_name": "omega-safe-prod",
    "region": "auto",
    "endpoint_url": "https://example.r2.cloudflarestorage.com",
    "storage_type_id": 2,
    "storage_type_name": "Cloudflare R2",
    "remote_path": "deltas/prod",
    "is_internal": false
  }
}

create-ecs-storage

#

Create a storage backend configuration on an HTTP ECS for Bring Your Own Storage — Provider Configuration. Use this to add a new BYOS storage entry, then inspect available storages with OmegaSafe CLI — list-ecs-storages or review one storage in detail with OmegaSafe CLI — view-ecs-storage. Skip optional arguments for interactive setup.

Arguments

• -e, --ecs-uuid <ECS_UUID> (Mandatory): Target ECS UUID.
• -a, --access-key-id <ACCESS_KEY_ID> (Optional): Access key ID.
• -b, --bucket-name <BUCKET_NAME> (Optional): Bucket name.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -k, --secret-access-key <SECRET_ACCESS_KEY> (Optional): Secret access key.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.
• -m, --remote-path <REMOTE_PATH> (Optional): Optional remote path prefix.
• -n, --storage-name <STORAGE_NAME> (Optional): Storage display name.
• -p, --provider <PROVIDER> (Optional): Provider (s3 or r2).
• -r, --region <REGION> (Optional): Bucket region (auto for R2).
• -u, --endpoint-url <ENDPOINT_URL> (Optional): Endpoint URL (required for R2).

Detailed behavior

• HTTP ECS only.
• Prompts for missing required values when not supplied non-interactively.
• Applies provider-specific validation rules (r2 requires endpoint and auto region; s3 forbids endpoint and auto region).
• Server-side storage setup verifies LIST, PUT, and GET against a temporary connection-test object. DELETE is tested too, but it is optional and enables best-effort cleanup after invalid uploads and explicit delete requests.
• Prints backend success message and also prints backend warning text when DELETE appears unavailable. That warning does not mean the storage is unusable for normal renewals, downloads, or claims.
• Interactive mode prints provider-specific least-privilege guidance.
• S3 guidance: allow s3:ListBucket on the bucket plus s3:GetObject and s3:PutObject on the target prefix. s3:DeleteObject is optional.
• R2 guidance: allow the S3-compatible equivalent of bucket LIST plus object GET and PUT on the target bucket or prefix. Object DELETE is optional.
• Signed Delta uploads cannot overwrite an existing object. Enable bucket versioning where available as additional protection against direct credential overwrites.

edit-ecs-storage

#

Edit an existing storage backend configuration on an HTTP ECS for Bring Your Own Storage — Editing Storage Settings. Use this to update an existing BYOS storage entry after identifying it with OmegaSafe CLI — list-ecs-storages or reviewing its current details with OmegaSafe CLI — view-ecs-storage. Skip optional arguments for interactive setup.

Arguments

• -e, --ecs-uuid <ECS_UUID> (Mandatory): Target ECS UUID.
• -s, --storage-uuid <STORAGE_UUID> (Mandatory): Storage UUID to edit.
• -a, --access-key-id <ACCESS_KEY_ID> (Optional): Access key ID (must be paired with secret).
• -b, --bucket-name <BUCKET_NAME> (Optional): New bucket name.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -h, --help (Optional): Show command help.
• -k, --secret-access-key <SECRET_ACCESS_KEY> (Optional): Secret access key (must be paired with access key ID).
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.
• -m, --remote-path <REMOTE_PATH> (Optional): Remote path prefix.
• -n, --storage-name <STORAGE_NAME> (Optional): New storage name.
• -p, --provider <PROVIDER> (Optional): New provider (s3 or r2).
• -r, --region <REGION> (Optional): New region.
• -u, --endpoint-url <ENDPOINT_URL> (Optional): Endpoint URL.
• -x, --keep-credentials (Optional): Keep existing credentials without prompt.
• -y, --update-credentials (Optional): Force credential update prompt path.

Detailed behavior

• HTTP ECS only.
• Loads current storage values and uses them as defaults for interactive edits.
• Enforces paired credential arguments and provider-change credential requirements.
• Re-applies provider-specific validation rules.
• Server-side storage setup verifies LIST, PUT, and GET against a temporary connection-test object. DELETE is tested too, but it is optional and enables best-effort cleanup after invalid uploads and explicit delete requests.
• Prints backend success message and also prints backend warning text when DELETE appears unavailable. That warning does not mean the storage is unusable for normal renewals, downloads, or claims.
• Interactive mode prints provider-specific least-privilege guidance.
• S3 guidance: allow s3:ListBucket on the bucket plus s3:GetObject and s3:PutObject on the target prefix. s3:DeleteObject is optional.
• R2 guidance: allow the S3-compatible equivalent of bucket LIST plus object GET and PUT on the target bucket or prefix. Object DELETE is optional.
• Signed Delta uploads cannot overwrite an existing object. Enable bucket versioning where available as additional protection against direct credential overwrites.

delete-ecs-storage

#

Delete a storage backend configuration from an HTTP ECS for Bring Your Own Storage — Deleting a Storage Entry. Use this to remove an existing BYOS storage entry after identifying it with OmegaSafe CLI — list-ecs-storages or reviewing its current details with OmegaSafe CLI — view-ecs-storage.

Arguments

• -e, --ecs-uuid <ECS_UUID> (Mandatory): Target ECS UUID.
• -s, --storage-uuid <STORAGE_UUID> (Mandatory): Storage UUID to delete.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -f, --force (Optional): Skip confirmation prompt.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• HTTP ECS only.
• Prompts for confirmation unless forced.
• Executes backend delete and prints backend result message.
• Without --force, cancellation path may print Deletion aborted..

fast-forward-claim

#

Advance the external claimed position of the latest local Delta without encrypting data. Useful for testing/recovery workflows that intentionally force Delta expiration.

Arguments

• -c, --claim-size <CLAIM_SIZE> (Mandatory): Number of bytes to advance.
• -k, --key-uuid <KEY_UUID> (Mandatory): Key UUID to adjust.
• -d, --config-dir <CONFIG_DIR> (Optional): Use a custom config directory.
• -f, --force (Optional): Skip confirmation prompt.
• -h, --help (Optional): Show command help.
• -l, --log-level <LOG_LEVEL> (Optional): Set logging verbosity.

Detailed behavior

• Resolves the latest local Delta for the key and the ECS linked to that local iteration.
• Reads the authoritative latest Delta pointer from ECS and requires it to be the same Delta iteration as the latest local Delta.
• If ECS already has a newer Delta than local state, the command aborts without mutating ECS or local cache state and instructs the user to run omegasafe pull-missing-deltas --key-uuid <uuid> first.
• Advances only the external Delta pointer (latest_claimed_global_position in ECS). It does not consume local PERFORMANCE or OFFLINE cache claims.
• On success, also updates the local key-level safety floor (latest_claimed_key_global_position) for that Delta cache entry so local replay/overlap checks stay aligned with ECS.
• Validates requested movement does not exceed remaining Delta capacity.
• Intended for testing/recovery workflows; use carefully because it consumes claim space.
• Prints current Delta claim state and remaining capacity.
• Prints requested forward movement and new claimed position.
• On success, prints updated claimed position and remaining capacity.
• Without --force, may print Operation aborted..

9. Encrypted File Behavior

#

The default encrypted output file suffix is .omegasafe, but neither the file name nor its extension affects decryption. Files can be renamed after creation or given a custom name at creation time with --file-name-override. The extension is not part of cryptographic validation or decryption logic.

Public encrypted-file format properties:

• .omegasafe is only the default output suffix used by encrypt when no file name override is provided.
• The outer file is a Encryption Method — Secure File Container with two internal entries: ENCRYPTED_DATA_UUID (the encrypted_data payload) and ENCRYPTION_METADATA_UUID (the encryption metadata payload, encryption_metadata.json).
• The encryption metadata contains only key_uuid and global_position_start — the minimum information required to start OmegaSafe decryption. It is unencrypted by default. It can be encrypted optionally with Encryption Method — Optional Traditional Encryption Layer.
• The encrypted file metadata (a fixed-size 1024-byte FileMetadata prefix inside encrypted_data) carries the original file name, original plaintext length, and a SHA-256 hash for integrity checking.
• A random encrypted suffix of 0%–5% of the original file size is appended to obscure exact plaintext size.
• If TRADITIONAL_ENC_LAYER_PASS or OMEGASAFE_TRADITIONAL_ENC_LAYER_PASS is set, the outer container is password-protected, the encryption metadata is encrypted too, and both sides must resolve the same password.

The current encrypt and decrypt commands load the full file payload into memory. A streaming fallback for insufficient-memory situations is on the roadmap.

For the full encrypted-file format specification, see Encryption Method — Encrypted File Format.

10. Claiming System

#

This section describes exactly how ECS claims, PERFORMANCE cache, OFFLINE cache, local sub-claims and cache top-ups behave.

Core Model

#

The claiming system tracks contiguous ranges of global positions. A claim is not a generic pool of reusable bytes; it is one reserved interval inside one key_iteration_uuid, and OmegaSafe moves through that interval from left to right as positions are consumed. That is why cache state is split per key iteration and why one request must fit inside one sufficiently large claim.

A local cache entry exists per key_iteration_uuid; there is not one shared cache for the whole key across all iterations. When a new key iteration becomes active, it starts with its own cache entry. Claims from one iteration are never mixed with claims from another iteration.

Inside one cache entry, OmegaSafe stores multiple LocalClaim records. Each LocalClaim is one contiguous interval previously reserved from ECS and tagged for one usage reason:

• cache_reason: performance or offline
• start_global_position: first position in the reserved interval
• end_global_position: last position in the reserved interval, inclusive
• latest_claimed_global_position: last position already consumed, inclusive

flowchart TD
    ENTRY["Local cache entry
one key_iteration_uuid"]
    ENTRY --> PERF1["Claim A
reason: performance
range: 1000..1999
latest: 1119"]
    ENTRY --> PERF2["Claim B
reason: performance
range: 6000..6999
latest: 5999"]
    ENTRY --> OFF1["Claim C
reason: offline
range: 9000..9999
latest: 9449"]

The cache_reason determines when a claim is preferred, but the bookkeeping math is identical for PERFORMANCE and OFFLINE claims. The important detail is that latest_claimed_global_position is a “last used” pointer, not a “next free” pointer.

When a claim is first created and nothing has been consumed yet, the stored pointer is:

latest_claimed_global_position = start_global_position - 1

That means the next usable position and remaining capacity are:

next_usable_position = latest_claimed_global_position + 1
remaining = end_global_position - latest_claimed_global_position

Because end_global_position is inclusive, a brand-new claim has total capacity of:

end_global_position - start_global_position + 1

flowchart LR
    START["Stored claim
start=3000001
end=4000000
latest=3000000"]
    NEXT["Next usable position
latest + 1 = 3000001"]
    TAKE["Request size = 500000
allocate 3000001..3500000"]
    SAVE["Update stored pointer
latest=3500000
remaining=500000"]
    START --> NEXT --> TAKE --> SAVE

Worked example: if a claim covers 3000001..4000000, its initial latest_claimed_global_position is 3000000. A request for 500000 positions receives the contiguous sub-claim 3000001..3500000. After that handoff, the stored pointer becomes 3500000, so the same claim still has 500000 positions remaining.

A single request is satisfied from one claim only. OmegaSafe does not stitch one request across multiple smaller claims, for encryption and decryption performance. For this reason fragmented local cache can still force an external path or OFFLINE failure even when the summed remaining capacity looks large enough. However, with default or larger cache sizes and typical file sizes, the lost capacity percentage in such cases is negligible.

Claim count pruning is shared across both PERFORMANCE and OFFLINE caches. Each reason keeps at most 10 local claims. If an 11th claim is added for one reason, the smallest remaining claim of that same reason is dropped. PERFORMANCE and OFFLINE limits are independent. In practice this keeps the number of local claims under control and removes the smallest remaining fragment for that cache reason; it does not track the last 10 encryptions.

Local High-Water Safety Guard

#

Each local cache entry also stores latest_claimed_key_global_position, which is the highest global position this CLI has already reserved locally for that key_iteration_uuid. This is a key-level safety floor and is separate from each LocalClaim record’s latest_claimed_global_position.

This matters because individual local claims can be fully consumed, pruned, or absent, while the CLI still needs to remember how far local state has already advanced. The same safety floor is also updated by flows such as fast-forward-claim, which can advance the external Delta pointer without consuming local PERFORMANCE or OFFLINE claims.

Before accepting any ECS-backed claim range for a Delta iteration, OmegaSafe CLI verifies that the returned start position is strictly above this local safety floor. If ECS returns a range starting at or below it, the CLI aborts with an unsafe overlap/replay error instead of continuing. Alpha claim paths apply the same rule using the Alpha cache entry as the local source of truth.

PERFORMANCE Cache

#

Purpose: Reduce ECS round-trips and obscure exact request sizes by claiming in chunks.

Behavior details:

• First attempt is always local PERFORMANCE cache when enabled.
• If local PERFORMANCE cache miss: refill size is chunked up with ceiling logic; one ECS claim is made, even if OFFLINE cache renewal is included.
• A local PERFORMANCE cache hit does not trigger any OFFLINE cache maintenance.
• PERFORMANCE cache is per key iteration (Delta). After key renewal (new Delta), a new cache entry starts empty for that new iteration.

Scenarios:

• P1: Local PERFORMANCE cache hit — PERFORMANCE claims: one claim with 5GB remaining; encryption request: 1GB; result: served locally from PERFORMANCE, no ECS call.
• P2: Local PERFORMANCE cache miss, refill one chunk — configured PERFORMANCE cache chunk: 10GB; PERFORMANCE cache remaining: 2GB; encryption request: 3GB; result: one ECS claim for 10GB (+OFFLINE top-up part only if needed), request served from the new PERFORMANCE cache claim.
• P3: Large encryption request, refill multiple chunks — configured PERFORMANCE chunk: 10GB; encryption request: 23GB; result: PERFORMANCE cache refill part is ceil(23/10)*10 = 30GB; request is served from first 23GB inside that new claim.
• P4: PERFORMANCE cache disabled — CACHE_PERFORMANCE_KEY_CAPACITY_GB=0; encryption request: 3GB; result: request claimed directly from ECS (or OFFLINE fallback if ECS unavailable). No PERFORMANCE claim is created.
• P5: Fragmented local PERFORMANCE cache — claims left: 700MB, 800MB, 900MB; encryption request: 850MB; result: smallest matching claim is 900MB claim. Encryption request: 950MB; result: no single claim can satisfy, external path runs. With default or larger cache sizes and typical file sizes, the capacity lost this way is negligible.
• P6: Claim count pruning — already 10 PERFORMANCE cache claims exist; new PERFORMANCE claim is added; result: smallest remaining PERFORMANCE claim is dropped to keep count at 10.

OFFLINE Cache

#

Purpose: Reserve pre-claimed capacity for no-network or intentionally offline operation. For OFFLINE_MODE setup in configuration, see OmegaSafe CLI — Dynamic Properties.

Top-up mechanics:

• OFFLINE has a target size equal to effective OFFLINE chunk bytes.
• OFFLINE is considered sufficient when total remaining OFFLINE capacity is >= target.
• OFFLINE top-up is triggered only when all are true:
  • OFFLINE target is > 0
  • current OFFLINE remaining is < target
  • claim flow is already on external path
  • OFFLINE_MODE is disabled
  • ECS is reachable
• Top-up amount is full target size, not just deficit.

Critical timing detail: OFFLINE top-up does not run during local PERFORMANCE cache hits. OFFLINE top-up runs opportunistically when an ECS claim is already needed for the request.

Fallback mechanics: OFFLINE sub-claim is used when external path is unavailable due to: explicit EcsConnectionError, HTTP ECS runtime errors with status 429 or 5xx, or HTTP ECS runtime errors indicating network or timeout failures. If error is not classified as unavailable (for example capacity/dependency logic errors), the error is propagated and OFFLINE fallback is not forced.

Scenarios:

• O1: User example (accurate behavior) — OFFLINE cache target config: 1GB; OFFLINE cache remaining: 1GB initially; offline usage consumes 10MB, remaining becomes 990MB; next time external path is used and ECS is reachable: OFFLINE is below target (990MB < 1GB) so OFFLINE top-up is added; top-up amount is full 1GB; new OFFLINE total becomes 1990MB; next top-up will not happen until OFFLINE remaining drops below 1GB again.
• O2: Exactly at threshold — target: 1GB; remaining: exactly 1GB; result: sufficient (>=), no top-up.
• O3: PERFORMANCE cache hit while OFFLINE is low — OFFLINE cache remaining below target; request is fully satisfied from PERFORMANCE cache; result: no ECS call, no OFFLINE top-up on that request.
• O4: PERFORMANCE cache disabled, OFFLINE cache low, ECS reachable — PERFORMANCE cache config is 0; request uses direct ECS claim path; if OFFLINE below target, external claim size becomes request + offline_target; request portion is returned immediately, tail is stored as OFFLINE claim.
• O5: ECS unavailable, OFFLINE sufficient — ECS fails with network/timeout/429/5xx; OFFLINE has a matching single claim; result: request served from OFFLINE.
• O6: ECS unavailable, OFFLINE fragmented — OFFLINE claims left: 600MB, 600MB; request: 900MB; result: fallback fails because no single OFFLINE claim can satisfy 900MB.
• O7: OFFLINE cache disabled by config — CACHE_OFFLINE_KEY_CAPACITY_GB=0; existing OFFLINE claims remain consumable; no new OFFLINE top-ups are created.
• O8: Claim count pruning — already 10 OFFLINE cache claims exist; new OFFLINE claim is added; result: smallest remaining OFFLINE claim is dropped to keep count at 10.

End-to-End Claim Decision Flow

#

For each encryption claim request of size request_size:

flowchart TD
    START["Encryption claim request
request_size"] --> PERFCHUNK["Compute effective PERFORMANCE chunk size"]
    PERFCHUNK --> PERFEN{"PERFORMANCE enabled?"}
    PERFEN -->|Yes| TRYLOCAL["Try local PERFORMANCE sub-claim"]
    PERFEN -->|No| EXTPATH["Go to external path"]
    TRYLOCAL --> LOCALHIT{"Local PERFORMANCE claim
can satisfy request?"}
    LOCALHIT -->|Yes| RETURNLOCAL["Return local PERFORMANCE sub-claim
No ECS call
No OFFLINE top-up"]
    LOCALHIT -->|No| EXTPATH
    EXTPATH --> OFFMODE{"OFFLINE_MODE enabled?"}
    OFFMODE -->|Yes| OFFFALLBACK["Try OFFLINE fallback sub-claim"]
    OFFMODE -->|No| ECSCHECK["Check ECS integrity"]
    ECSCHECK --> TOPUP["Check OFFLINE remaining
against target"]
    TOPUP --> CLAIMSIZE["Build one external claim size:
PERFORMANCE part
+ optional OFFLINE top-up part"]
    CLAIMSIZE --> ECSCLAIM["Make one ECS claim"]
    ECSCLAIM --> ECSRESULT{"External path result"}
    ECSRESULT -->|Unavailable| OFFFALLBACK
    ECSRESULT -->|Other error| PROPERR["Propagate original error"]
    ECSRESULT -->|Success| SAFECHK{"Returned ECS range start
strictly above local high-water?"}
    SAFECHK -->|No| UNSAFE["Fail: unsafe ECS claim rejected"]
    SAFECHK -->|Yes| SPLIT["Partition returned range:
PERFORMANCE segment
+ optional OFFLINE segment"]
    SPLIT --> PERFRETURN{"PERFORMANCE enabled?"}
    PERFRETURN -->|Yes| RETURNPERF["Return request from new PERFORMANCE claim"]
    PERFRETURN -->|No| RETURNDIRECT["Return direct ECS request segment"]
    OFFFALLBACK --> OFFOK{"One OFFLINE claim can
satisfy request?"}
    OFFOK -->|Yes| RETURNOFF["Return OFFLINE sub-claim"]
    OFFOK -->|No| OFFFAIL["Fail: insufficient OFFLINE cache"]

1. Compute effective PERFORMANCE chunk size.
2. If PERFORMANCE is enabled (>0), try local PERFORMANCE sub-claim first.
3. If local PERFORMANCE can satisfy request, return immediately. No ECS call is made, and no OFFLINE top-up is attempted.
4. If PERFORMANCE is missing/insufficient, go to external path:
   • If OFFLINE_MODE is enabled, external is intentionally skipped and OFFLINE fallback path is used.
   • Otherwise, ECS integrity is checked.
   • Before accepting the ECS-backed range, OmegaSafe verifies that its start is strictly above local latest_claimed_key_global_position. If not, the claim is rejected as unsafe.
   • OFFLINE top-up need is checked against total OFFLINE remaining.
   • One external claim is made whose size is:
     • PERFORMANCE portion: if PERFORMANCE enabled: ceil(request_size / performance_chunk) * performance_chunk; if PERFORMANCE disabled: request_size
     • plus OFFLINE portion: add full offline_target_size only if OFFLINE remaining is below target
5. The single external claim range is partitioned: first segment → PERFORMANCE claim (if enabled); tail segment → OFFLINE claim (if OFFLINE top-up needed).
6. Return claim to encryption: if PERFORMANCE enabled: request is sub-claimed from the newly added PERFORMANCE claim; if PERFORMANCE disabled: return the direct request segment from external claim.
7. If external path errors as “ECS unavailable”, fallback to OFFLINE sub-claim.
8. If OFFLINE cannot satisfy fallback, fail with runtime error.

Sub-Claim Selection Rule

#

Sub-claim selection is identical for both PERFORMANCE and OFFLINE reasons:

• Candidate set: claims of the requested reason where remaining >= request_size.
• Selected claim: the one with the smallest remaining capacity among candidates (best-fit strategy).

Important consequence: Claims are not split across multiple sub-claims in one request. Example: two OFFLINE claims with 600MB + 600MB remaining cannot satisfy one 900MB request, even though total is 1.2GB. A single claim of at least 900MB is required. Continuous claim blocks are necessary for encryption/decryption performance.

Exhaustive Decision Matrix

#

These cases restate the same decision logic vertically so they remain readable on narrower layouts.

M1

#

Result: OmegaSafe returns a local PERFORMANCE sub-claim immediately. ECS is not contacted, and OFFLINE top-up is not evaluated because the request is already satisfied locally.

M2

#

Result: OmegaSafe returns a local PERFORMANCE sub-claim immediately, exactly as in M1. OFFLINE_MODE has no effect here because the request never reaches the external path.

M3

#

Result: OmegaSafe makes one ECS claim for the PERFORMANCE refill portion only, stores that range as a new PERFORMANCE claim, and returns the request from that new PERFORMANCE claim. No OFFLINE claim is added because OFFLINE is already at or above target.

M4

#

Result: OmegaSafe makes one ECS claim that covers both the PERFORMANCE refill portion and a full OFFLINE top-up portion. The returned range is split into a PERFORMANCE claim and an OFFLINE claim, and the request is served from the new PERFORMANCE claim.

M5

#

Result: OmegaSafe cannot complete the external path, so it falls back to OFFLINE and tries to make one OFFLINE sub-claim. The request succeeds only if one OFFLINE claim can satisfy the full request; otherwise the command fails with insufficient OFFLINE cache.

M6

#

Result: OmegaSafe skips the external path intentionally and goes straight to OFFLINE fallback. The request succeeds only if one OFFLINE claim can satisfy the full request; otherwise the command fails with insufficient OFFLINE cache.

M7

#

Result: OmegaSafe makes one ECS claim exactly equal to the request size and returns that direct external segment to encryption. No PERFORMANCE claim is created, and no OFFLINE top-up is added because OFFLINE is already sufficient.

M8

#

Result: OmegaSafe makes one ECS claim for the request size plus a full OFFLINE target top-up. The request portion is returned directly, and the tail portion is stored as a new OFFLINE claim.

M9

#

Result: Because PERFORMANCE is disabled and the external path is unavailable, OmegaSafe tries OFFLINE fallback directly. The request succeeds only if one OFFLINE claim can satisfy the full request; otherwise the command fails with insufficient OFFLINE cache.

M10

#

Result: OmegaSafe skips the external path intentionally and tries OFFLINE fallback immediately. The request succeeds only if one OFFLINE claim can satisfy the full request; otherwise the command fails with insufficient OFFLINE cache.

M11

#

Result: Once OmegaSafe has entered the external path, a non-“unavailable” ECS error is treated as the authoritative failure. The original error is propagated, and OFFLINE fallback is not forced.

M12

#

Result: OmegaSafe is already on the OFFLINE fallback path, but no single OFFLINE claim can satisfy the full request. The command fails with a runtime error about insufficient OFFLINE cache; smaller OFFLINE fragments are not stitched together.

Edge Cases And Exact Rules

#

• E1: Best-fit is single-claim only — if total remaining across multiple claims is enough but no single claim is enough, request is treated as insufficient locally.
• E2: Threshold is strict <, not <= — OFFLINE top-up happens only when remaining is below target. At exactly target, top-up does not run.
• E3: Top-up amount is full target, not deficit — target=1GB, remaining=990MB → top-up adds 1GB, new remaining becomes 1990MB.
• E4: PERFORMANCE refill rounds up by chunk — request=23GB, chunk=10GB → refill portion is 30GB.
• E5: Safety cap can reduce effective chunk/target — even with large configured GB, effective size is capped to 25% of current key capacity.
• E6: Keys below 4 bytes of total capacity effectively disable cache chunks — effective cache size is min(configured_bytes, int(key_capacity * 0.25)); key_capacity of 1, 2, or 3 bytes yields 0 effective PERFORMANCE/OFFLINE chunk bytes after the 25% cap; at 4 bytes of key capacity, the capped chunk/target becomes 1 byte.
• E7: Per-reason claim list is pruned at 10 — adding an 11th claim for one reason drops the smallest-remaining claim of that reason.
• E8: Import flow can initialize claims — import-key runs a small encryption to pull deltas and may create initial PERFORMANCE/OFFLINE cache claims.

Capacity Configuration

#

CACHE_PERFORMANCE_KEY_CAPACITY_GB and CACHE_OFFLINE_KEY_CAPACITY_GB are chunk/target sizes in decimal GB (1 GB = 1,000,000,000 bytes). Defaults are 10 and 10. Allowed values are 0..1000 inclusive. Fractional values are allowed (0.5 = 500,000,000 bytes). These are configured as OmegaSafe CLI — Dynamic Properties and can be changed via OmegaSafe CLI — set-config And Dynamic Settings.

Effective bytes are not raw config bytes. They are capped:

effective_bytes = min(config_bytes, int(key_capacity * 0.25))

25% safety cap rule: Even with large configured GB, effective size is capped to 25% of current key capacity. This prevents over-claiming relative to the key’s total capacity.

Effects of setting to 0:

• CACHE_PERFORMANCE_KEY_CAPACITY_GB=0: PERFORMANCE cache refill is disabled; request is claimed directly from ECS (or OFFLINE fallback if ECS unavailable). Disabling PERFORMANCE cache is not recommended: it reduces not only operational performance, but also removes the chunked-claim obfuscation layer that would otherwise make individual encryption claim sizes less visible to ECS.
• CACHE_OFFLINE_KEY_CAPACITY_GB=0: OFFLINE top-up target is disabled. Existing OFFLINE claims can still be consumed.

Delta Pulling Semantics

#

This section defines exactly which Deltas are pulled from ECS, and when.

Shared rules:

• A “missing delta” means: ECS references a delta_uuid that is not present in local key storage.
• Pulling is idempotent by UUID: if a requested delta_uuid is already local, it is skipped.
• Delta payloads in ECS are expected to be encrypted Secure File Containers (SFC); see Encryption Method — Secure File Container. Upload and import paths validate this format.
• Pull reconciliation is additive for valid missing-delta sets.
• OmegaSafe CLI — pull-missing-deltas uses the same local/ECS UUID conflict guard as other reconciliation paths and then imports each missing delta sequentially.
• OmegaSafe CLI — import-key-delta is a manual local-file import path intended for exceptional recovery workflows; it does not query ECS and does not reconcile remote state. It still requires locally actionable key context (local Alpha + cache-resolved ECS UUID link created by prior successful ECS-backed operation for that key). It is not intended as a bypass for keys that were never ECS-linked locally.
• Conflict handling is flow-specific:
  • Reconciliation conflict (same seq_number, different UUID): hard fail with an explicit recovery message. No pull is attempted, and no additional local delta is saved for that sequence. This is defensive for pre-existing inconsistent states. It is not expected to be created by normal CLI renewal flows.
  • Renewal-upload conflict (newly generated local delta conflicts with ECS on sequence): upload/registration fails, renewal is rolled back, and transient local artifacts for that renewed iteration UUID are removed (best effort) before exiting with failure.

encrypt behavior:

Quick description: If encryption reaches the external ECS path and local Delta state is behind, OmegaSafe reconciles first and catches up to the newest remote Delta in one pass.

• Delta pulling is only evaluated when encryption enters the external claim path (ECS path).
• If encryption is satisfied by a local PERFORMANCE cache claim, no ECS integrity check runs and no delta pull is attempted.
• On ECS path, integrity check defines missing set as: all remote Deltas where seq_number > local_seq.
• Encryption pulls all UUIDs in the missing set before retrying claim logic.
• If a same-sequence UUID conflict is detected, encryption fails immediately with recovery instructions instead of pulling.
• If ECS capacity is exhausted and renewal is attempted, the newly generated Delta is uploaded before local commit. If upload fails due to sequence conflict, renewal fails and is rolled back; the transient renewed local delta/cache entry is cleaned up (best effort).

import-key behavior:

Quick description: import-key eagerly catches the key up to the current remote Delta state by triggering the same reconciliation path used by encrypt.

• import-key imports Alpha and creates local cache entry first.
• It then runs a small synthetic encryption request specifically to trigger the same reconciliation logic as encrypt.
• This same synthetic run may also initialize PERFORMANCE/OFFLINE local claim records, unless caching is disabled.
• If that synthetic run sees same-sequence UUID conflict, it fails with recovery instructions (no duplicate pull).

decrypt behavior:

Quick description: decrypt pulls only the Delta chain needed for the specific file being decrypted, not every newer remote Delta by default.

• Decrypt first resolves which Delta contains the file’s global_position_start.
• If that required Delta is already local, no pull is performed.
• If not local, decrypt queries ECS and identifies the target sequence that contains the position.
• It then pulls missing Deltas with seq_number <= target_seq (up to and including required Delta).

pull-missing-deltas behavior:

Quick description: pull-missing-deltas explicitly catches local state up to all Deltas currently known by ECS for that key.

• Requires locally actionable key context (local Alpha + cache-resolved ECS link).
• Reads ECS Deltas for the key, compares UUID presence against local Delta iterations, and builds missing set.
• For each missing Delta, downloads encrypted payload from ECS, decrypts with local Alpha, validates decrypted key metadata, and saves to local key/cache containers.
• Fails immediately on same-sequence UUID conflict.

import-key-delta behavior:

Quick description: import-key-delta is a manual recovery import from a local encrypted Delta file and does not query ECS or reconcile remote state.

• Manual import from a local encrypted delta file (--input-file), with explicit warning prompt unless --force is set.
• Reads encryption metadata to identify key_uuid, requires matching local Alpha and cache-resolved ECS UUID for that key, decrypts payload using Alpha, validates it is a Delta (seq_number > 0), then saves locally.
• Enforces strict local continuity for manual import: imported Delta sequence must be exactly latest_local_seq + 1 (unless the same iteration UUID is already present locally, in which case import is a no-op).
• Does not contact ECS and does not perform ECS reconciliation.
• Local sequence guard still applies: if a different local delta UUID already exists for the same sequence, import fails with recovery guidance.

Delta pulling examples:

• D1 (encrypt, local behind latest): local latest: seq 4; ECS latest: seq 7; result: encryption pulls missing seq 5, 6, 7 before claim continues.
• D2 (encrypt, same-seq conflict): local latest: seq 7, uuid A; ECS has seq 7, uuid B; result: encryption fails immediately with a critical conflict message and recovery steps; it does not pull B.
• D3 (encrypt, local cache hit): request is satisfied from local PERFORMANCE cache; result: no ECS reconciliation, no delta pull.
• D4 (decrypt, not all remote deltas needed): local has seq 1; ECS has seq 1..8; file position belongs to seq 3; result: decrypt pulls missing seq 2 and 3; it does not pull seq 4..8 in this run.
• D5 (import-key): only Alpha exists locally after import; ECS has seq 1..6; result: synthetic encryption reconciliation pulls seq 1..6 during import-key.
• D6 (encrypt, renewal upload conflict rollback): local active iteration: seq 7; renewal creates transient local seq 8, uuid X; ECS already has seq 8, uuid Y; result: delta upload/registration is rejected due to sequence conflict, renewal fails, and transient local artifacts for X are rolled back (best effort cleanup of local key/cache entries for that iteration UUID); next attempt reconciles against ECS and can pull authoritative seq 8 uuid Y.
• D7 (pull-missing-deltas, explicit eager catch-up): local has Alpha and seq 1; ECS has seq 1..4; result: command pulls seq 2, 3, 4 in one run and saves them locally.
• D8 (import-key-delta, ECS unavailable recovery path): user has local Alpha, existing local cache ECS linkage for that key, and a manually downloaded encrypted Delta file from BYOS bucket; ECS API is unavailable; result: command decrypts that Delta with local Alpha and saves it locally; no ECS call is required.

11. Source Code integrations

#

The OmegaSafe CLI source code package can be downloaded from the Source Code option in the signed-in download page.

The source code package is provided under a source-available custom licence. Depending on the included LICENSE, authorised users may be able to modify the source code and build their own CLI binary or distribution package for direct integration with their software. Any such integration remains subject to the included LICENSE, Terms and Conditions — OmegaSafe Cloud - Terms and Conditions of Use, and any written service agreement that expressly overrides them.

Relevant documentation and the applicable LICENSE are included in the source code package itself. Review those included files before modifying, building, packaging, or integrating the software.

12. Related Topics

#

• Encryption Method — Byte-Replacement Map Model
• Keys Management — Key Sharing Model
• Bring Your Own Storage — Recommendation
• OmegaSafe API — API Conventions