Skip to content

DAH-2592: describe the real lium CLI in the agent skill #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
arhangel66 merged 3 commits into from
Aug 5, 2026
Merged

DAH-2592: describe the real lium CLI in the agent skill #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c8802bf
Rewrite the CLI reference from lium v0.0.29 --help output
arhangel66 Aug 5, 2026
76add51
Fix review findings: ps/logs take no index, ls exits 0 on failure
arhangel66 Aug 5, 2026
300f85e
Fix keyword-only SDK signatures in the reference
arhangel66 Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 59 additions & 33 deletions lium/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ lium init --no-browser # existing account, headless
Verify setup:

```bash
lium ls # if this works, auth is OK
lium balance # prints a balance -> auth works; prints an error -> it does not
```

### Alternative Install (via pip/uv)
Expand Down Expand Up @@ -226,24 +226,26 @@ For fallback options, the user must get an API key from https://lium.io Account

```bash
lium config show # check stored config
lium ls # if this works, auth is OK
lium balance # prints a balance -> auth works
```

### Non-Interactive Pod Creation

Always use `-y` flag and pass all parameters:
Always use `-y` flag and pass all parameters. Add `--no-ssh` too: without it a
successful `lium up` ends by opening an interactive SSH session, which stalls an
agent (`--image` mode streams container logs instead).

```bash
# WRONG (interactive):
lium up # prompts for executor and template selection
lium up 1 # prompts for template selection
lium up # one confirmation prompt before renting
lium up 1 # same — the prompt is the acquire confirmation

# RIGHT (non-interactive):
lium up --gpu H100 -y # auto-selects executor + default template
lium up --gpu A100 -c 2 --country US -y # with filters
lium up --gpu H100 --name my-pod --ttl 6h -y # with name and auto-termination
lium up --gpu A6000 --image pytorch/pytorch:2.0 -y # custom docker image
lium up --gpu H100 --jupyter -y # with Jupyter
lium up --gpu H100 -y --no-ssh # auto-selects node + default template
lium up --gpu A100 -c 2 --country US -y --no-ssh # with filters
lium up --gpu H100 --name my-pod --ttl 6h -y --no-ssh # with name and auto-termination
lium up --gpu A6000 --image pytorch/pytorch:2.0 -y # custom docker image (streams logs)
lium up --gpu H100 --jupyter -y --no-ssh # with Jupyter
```

### Non-Interactive Funding
Expand All @@ -270,23 +272,35 @@ export PATH="$HOME/.lium/bin:$PATH" # needed in current shell session

After completing the two-step auth, run `lium ls` to verify. If it returns results, auth is done.

#### `lium ps` Has No `--format json`
#### An Error Does Not Always Mean a Non-Zero Exit

Only `lium exec`, `lium rm` and `lium up` exit non-zero when they fail. Everything
else — including **`lium ls`** — can print `Error: ...` and still exit **0**:

```bash
lium ps --format json # Error: No such option
lium ps # correct
lium ssh no-such-pod-xyz # prints "No active pods", exits 0
lium ls >/dev/null && echo "auth OK" # prints "auth OK" even with a revoked key
```

Use the pod **name** (e.g. `lunar-lion-4c`) from `lium ps` output for targeting — not a numeric index.
So `lium ls` is **not** a usable auth check. Never treat `$?` alone as proof that
a step worked. Read the output, or prefer the machine-readable modes
(`lium ls --format json`, `lium ps --format json`, `lium exec --json`) and check
the result there — an empty `[]` from `lium ls --format json` means "no nodes",
while an error line on stderr means the call failed. Tracked as DAH-2593.

#### Pod Targeting — Prefer Names

#### Commands Without -y Flag
Use the pod **name** (e.g. `lunar-lion-4c`) from `lium ps` output for targeting — not a numeric index; indices shift with every listing.

Not all commands support `-y`. Workaround for interactive commands:
#### `-y` Exists on the Destructive Commands

`lium rm`, `lium up`, `lium fund`, `lium volumes rm`, `lium bk set/rm/restore` all
take `-y, --yes`. No piped `yes` is needed:

```bash
lium rm my-pod # will prompt for confirmation
echo "y" | lium rm my-pod # workaround for agent use
echo "y" | lium rm -a # remove all pods non-interactively
lium rm my-pod -y # non-interactive
lium rm -a -y # remove all pods non-interactively
```

#### Templates
Expand All @@ -299,7 +313,13 @@ echo "y" | lium rm -a # remove all pods non-interactively

#### No User Identity Command

lium CLI has no `whoami` command. To verify auth works, use `lium ls` — if it returns results, auth is OK.
lium CLI has no renter-side identity command — no `whoami` for your API key.
(`lium provider portal whoami` exists, but it reports the *provider* portal session,
not the API key you rent with.)

To check the key, run `lium balance`: it prints a balance when the key works and an
error when it does not. Do **not** use `lium ls` for this — it prints an error and
exits 0 on an auth failure, so `lium ls && echo OK` says OK with a revoked key.

#### Long-Running Commands Over SSH

Expand Down Expand Up @@ -389,18 +409,18 @@ For reliable failure diagnosis, poll `lium ps` every ~10-30s for the first few m

#### "Executor Not Found" on `lium up <id>`

If an executor is visible on the lium.io dashboard but `lium up <executor_id>` or `lium ls` doesn't show it, the platform's availability filter rejected it. Reasons include: low free disk space, high disk utilization, unresponsive health checks, or missing verification. **`lium ls` is the source of truth for rentable machines** — prefer filtering/selecting from `lium ls` output rather than matching IDs from the website.
If an executor is visible on the lium.io dashboard but `lium up <node-id>` or `lium ls` doesn't show it, the platform's availability filter rejected it. Reasons include: low free disk space, high disk utilization, unresponsive health checks, or missing verification. **`lium ls` is the source of truth for rentable machines** — prefer filtering/selecting from `lium ls` output rather than matching IDs from the website.

## CLI Quick Reference

### Discovery

```bash
lium ls # all available GPUs (shows table with ★ for best price/perf)
lium ls H100 # filter by type
lium ls --gpu H100 # filter by GPU type (there is no positional argument)
lium ls --sort download # sort by download speed (fastest first) — preferred default
lium ls --sort upload # sort by upload speed
lium ls --sort price_gpu # sort by price per GPU/hour (default)
lium ls --sort price_gpu # sort by price per GPU/hour
lium ls --format json # machine-parseable output
lium templates # list Docker templates
lium templates pytorch # search templates
Expand All @@ -412,12 +432,13 @@ lium templates pytorch # search templates

```bash
lium up --gpu H100 -y # create pod
lium ps # list active pods (no --format json support)
lium ps # list active pods
lium ps --format json # machine-readable pod list
lium ssh my-pod # SSH into pod
lium exec my-pod "nvidia-smi" # run command
lium exec all "pip install torch" # batch exec on all pods
lium rm my-pod # stop pod
lium rm all # stop all pods
lium rm my-pod -y # stop pod
lium rm -a -y # stop all pods
```

### Streaming Pod Logs
Expand Down Expand Up @@ -451,9 +472,14 @@ Always use `--format json` when parsing output programmatically:

```bash
lium ls --format json | python -c "import json,sys; print(json.load(sys.stdin))"
lium ps --format json | python -c "import json,sys; print(json.load(sys.stdin))"
```

Note: `lium ps` does NOT support `--format json`.
`--format [table|json]` exists on `lium ls` and `lium ps`. `--json` — a plain flag,
not a format choice — is taken by `lium exec`, `lium fund`, `lium balance`,
`lium signup`, `lium topup create`, `lium topup currencies`, and by the whole
`lium provider` group (set it on the group: `lium provider --json node list`).
`lium templates` has neither, and neither does anything else.

## End-to-End Agent Workflow

Expand All @@ -475,24 +501,24 @@ lium init --no-browser
# → wait for user to confirm they approved
lium init --session <SESSION_ID>

# 3. Verify
lium ls >/dev/null 2>&1 && echo "OK" || echo "Auth failed"
# 3. Verify (lium ls exits 0 even on an auth failure — check balance instead)
lium balance --json

# 4. Find suitable GPU (sort by speed by default)
lium ls --gpu H100 --sort download

# 5. Create pod (non-interactive!)
lium up --gpu H100 --name work-pod --ttl 6h -y
# 5. Create pod (non-interactive! --no-ssh returns instead of opening a session)
lium up --gpu H100 --name work-pod --ttl 6h -y --no-ssh

# 6. Wait and verify (note: --format json is NOT supported for lium ps)
lium ps
# 6. Wait and verify (read the output, not just the exit code)
lium ps --format json

# 7. Use the pod
lium scp work-pod ./code.py
lium exec work-pod "python /root/code.py"

# 8. Cleanup
echo "y" | lium rm work-pod
lium rm work-pod -y
```

## Detailed References
Expand Down
Loading
Loading