Flux CLI

Cross-platform CLI for managing training tasks and projects on Flux. It outputs structured JSON by default and is designed for AI Agent integration.

Features

• Cross-platform binary — macOS / Linux / Windows (amd64 & arm64)
• Secure authentication — API key stored in system keychain (macOS Keychain / Windows Credential Manager / Linux Secret Service)
• Multi-profile config — switch quickly between dev / staging / prod environments
• Full task lifecycle — create, edit, run, stop, delete, logs, hyperparameters, and batch operations
• Agent-friendly output — JSON by default + JSONL request logs for automation
• Resilient requests — built-in retry with exponential backoff, configurable timeout and concurrency

Installation

npm install -g @limxdynamics/flux-cli

Requires Node.js >= 16. The installer auto-selects the correct binary for your OS/architecture.

Verify

flux --version

Quick Start

# 1. Login (API key saved to system keychain)
flux auth login --api-key "gm_sk_your_key"

# 2. Verify connection
flux auth status        # local check
flux auth whoami        # server check

# 3. Start using
flux task list
flux project list

Create API keys in Flux: avatar menu (bottom-left) → API Key Management. The full key is shown only once at creation time.

Command Overview

flux
├── auth        login / logout / status / whoami
├── config      set / get / profile (list / set / use)
├── project     list / create / info / edit / delete
└── task        create / edit / copy / list / info / run / stop / delete
                logs / resource / image / storage / data / hp / env
                params / tag / batch / model

Use flux --help or flux <command> --help for details.

Common Examples

# Task management
flux task list --page 1 --limit 50
flux task info --task-id "task_xxx"
flux task create --file ./create.json
flux task run --task-id "task_xxx"
flux task logs --task-id "task_xxx" --follow --interval 2s --timeout 5m
flux task stop --task-id "task_xxx"

# Project management
flux project list --page 1 --limit 50
flux project create --file ./project-create.json

# Profile switching
flux config profile set dev --base-url "https://dev.example.com/prod-api" --timeout 30s
flux config profile use dev

# Output control
flux task list --human          # human-readable table
flux task list --quiet          # key fields only
flux task list --debug          # debug logs

Configuration

Priority: CLI flags > Environment variables > Config file

| Variable | Description | |----------|-------------| | FLUX_BASE_URL | Service endpoint | | FLUX_API_KEY | API key (temporary, not persisted) | | FLUX_TIMEOUT | Request timeout (e.g. 30s) | | FLUX_RETRY | Retry count | | FLUX_CONCURRENCY | Concurrency limit | | FLUX_PROFILE | Temporary profile |

Config file location:

• macOS / Linux: ~/.config/gradmotion/config.yaml
• Windows: %APPDATA%\gradmotion\config.yaml