rucio / rucio/documentation

Fix outdated CLI syntax in `using_the_client.md`

Open
#694 1 comment 0 reactions 1 assignee View on GitHub

@voetberg is already working on this.

Since Sep 1, 2026.

Discussion needed enhancement
Dominant language
Python
Stars
4
Forks
71
Avg merge
2d 1h
Merged PRs (30d)
11

Description

Problem:
Documentation shows outdated CLI syntax that fails in Rucio 38.5.1:

rucio -a=root -S=OIDC -v whoami  # Error: No such option: -a

https://github.com/rucio/documentation/blob/4d8b8a1da3240e16a895ba7b0f0323abc159906e/docs/user/using_the_client.md?plain=1#L122-L124
ff.

Logs:

[root@rucio-server-8658d7545c-drzb5 tmp]# rucio --version
Unable to load schema module rucio_it_tools.rucio_it_sme_policy.schema from policy package, falling back to generic
rucio 38.5.1
[root@rucio-server-8658d7545c-drzb5 tmp]# rucio -a=root -S=OIDC -v whoami
Unable to load schema module rucio_it_tools.rucio_it_sme_policy.schema from policy package, falling back to generic
Usage: rucio [OPTIONS] COMMAND [ARGS]...
Try 'rucio -h' for help.

Error: No such option: -a

Question: How do we prevent docs from becoming outdated?

Potential Solutions:

  1. Automated CLI testing in CI - Run documented commands as part of CI
  2. Version-specific docs - Separate doc branches per major release
  3. Breaking change checklist - Require doc updates in PRs that change interfaces
  4. Executable examples - Use integration tests as living documentation

Immediate Action Needed:

  • Fix current CLI examples to match v38.5.1 syntax
  • Decide on long-term documentation maintenance strategy

Should we create issues for:

  1. Fixing the outdated CLI examples?
  2. Implementing automated doc validation in CI?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.