Skip to content

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

Merged
arhangel66 merged 3 commits into
mainfrom
DAH-2592-skill-cli-docs-sync
Aug 5, 2026
Merged

DAH-2592: describe the real lium CLI in the agent skill#5
arhangel66 merged 3 commits into
mainfrom
DAH-2592-skill-cli-docs-sync

Conversation

@arhangel66

@arhangel66 arhangel66 commented Aug 5, 2026

Copy link
Copy Markdown
Collaborator

DAH-2592. Rewrites the agent-facing CLI reference against the shipped binary
(lium v0.0.29). Documentation only — no CLI code.

Why

lium/references/cli-commands.md did not merely lag the CLI, it invented parts of
it: ls --region/--min-memory/--max-price and a positional GPU_TYPE, ps -a/--sort,
ssh --command/--port/--key, exec --timeout/--output, scp -r/-p,
rsync --delete/--exclude/--dry-run, themes monokai/solarized/dracula/nord where
the CLI takes dark|light. It also denied two capabilities that exist — "lium rm
has no -y, use echo y |" and "lium ps does not support --format json". A
denial is worse than silence: it stops an agent using a command that works.

Seven commands (balance, topup, update, ssh-keys, mine, provider,
gpu-splitting) were missing entirely, and real flags went undocumented —
up --no-ssh/--dockerfile/--ssh-name/--volume-encryption, fund --alpha/-k/--json,
exec -s/--script,-e/--env,--json, ls --count/--min-cuda/--sort/--limit,
ps [POD_ID], scp -d/--download, config path/reset/unset, bk restore-logs.

How it was verified

lium <cmd> --help was captured for all 27 top-level commands and all 62
sub-commands, and every section is diffed against its dump in both directions:
each real flag must appear in the doc, and each flag token in the doc must exist
somewhere in the real help. Sentences that deliberately state a flag does not
exist are exempt — they are what stops an agent re-inventing it.

Behavioural claims that --help cannot answer were read from the source instead.
That is where the two sharpest fixes came from:

  • lium ls exits 0 when it fails. GetExecutorsAction swallows every
    exception and the command prints it and returns, so lium ls >/dev/null && echo OK
    reports OK with a revoked API key. Both files used exactly that as their auth
    check; they now use lium balance. Only exec, rm and up are reliable — the
    rest is DAH-2593.
  • ps and logs do not accept an index. They compare the argument literally
    against pod ids and names, so lium ps 1 reports "not found". Pod Targeting is now
    a per-command table rather than one "all of them accept" claim.

Also corrected: --sort price_gpu was labelled the default (it is download);
lium up needs --no-ssh or it ends in an interactive SSH session and stalls an
agent; exit codes 3 and 6 are defined but unreachable, so the table publishes
0/1/2/4/5 plus an explicit warning about exit 0; lium mine is provider-side, not
renter-side; LIUM_SSH_KEY does not exist.

llms-full.txt is regenerated in the same change, as check-llms-full.yml requires.

Parallel PRs cover the same drift in lium-docs and in the lium-toolkit:cli
plugin skill.

Supersedes #4

#4 synced the same reference against v0.0.27 from a base that predates #3. Every
claim it fixed is covered here and re-verified against v0.0.29: ps does take
--format json, target pods by name rather than by index, theme accepts only
dark|light, LIUM_SSH_KEY does not exist, and the machine-readable-output map is
published as a table.

The one thing #4 carried that this branch did not is its sdk-reference.md
one-liner, now included. Lium.exec is exec(self, pod, *, command, ...), so the
documented lium.exec(pod, "python /root/train.py") raises TypeError.

Checking the rest of that file for the same defect found it in fifteen more
signatures — scp, upload, download, rsync, switch_template, restore,
backup_now, install_jupyter, schedule_termination and the rest all take
keyword-only arguments the table showed as positional. Two parameters did not exist
at all (exec(..., timeout=), backup_create(..., name=)) and restore's
target_path is really restore_path. Signatures now use Python's own *
notation, with a line above the tables explaining it.

#4 can be closed.

@arhangel66
arhangel66 marked this pull request as ready for review August 5, 2026 16:34
@arhangel66
arhangel66 merged commit 2c8628c into main Aug 5, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant