Replace robot/rebot CLI parsing with confargs and add config file support by bhirsz · Pull Request #5773 · robotframework/robotframework

bhirsz · 2026-08-31T08:53:07Z

Summary

Replaces the hand-rolled getopt-based command-line parsing of the robot
and rebot tools with the declarative confargs
library, and adds configuration-file support (closes #5337).

Behaviour of the parsed options is preserved — the downstream
RobotSettings / RebotSettings defaulting is unchanged — and, thanks to
confargs' opt-in lenient name matching, the command-line syntax stays
backwards compatible too (case- and hyphen-insensitive long names,
unique-prefix abbreviation, --no<flag> negation). See Compatibility below.

Draft: opened for discussion of the approach before polishing docs/acceptance
tests.

What changed

Area	Change
`robot.conf.arguments`	New. Explicit confargs `ArgConfig` subclasses `RobotArgs` / `RebotArgs` (shared base `_CommonArgs`) declaring every option as a plain, pass-through confargs option. This is the single source of truth for the CLI. Both enable `cli_case_insensitive` / `cli_ignore_hyphens` / `cli_allow_abbrev`.
`robot.utils.confargsparser`	New. `ConfargsParser` — a thin adapter exposing the same surface `Application` expects (`name`, `version`, `parse_args(args) -> (opts, datasources)`), raising `Information` for `--help`/`--version` and `DataError` on failure.
`robot.utils.application`	`Application.__init__` gained an optional `config=` param; when set it builds a `ConfargsParser`, otherwise the legacy `ArgumentParser`.
`robot.run` / `robot.rebot`	Pass `config=RobotArgs` / `config=RebotArgs`.
`robot.utils.argumentparser`	Unchanged. `libdoc` / `testdoc` keep using the legacy parser.
`setup.py`	Adds `confargs>=0.7` dependency.

No dynamic class generation and no pre-processing/normalisation of argv on the
Robot Framework side — options are handed to confargs directly, mirroring the
tests/robot_cli.py
reference fixture. The legacy leniencies that RF users rely on (case/hyphen
insensitivity, joined negation, unique-prefix abbreviation) are restored via
confargs' own opt-in features rather than a robot-side canonicalisation layer.

Configuration file support (#5337)

Sources are merged with precedence:

command line  >  environment variables  >  config file  >  option default

Config is read from a [tool.robot] / [tool.rebot] table, discovered by
walking up from the working directory (stopping at .git) plus the per-user
config dir. config_names = robot.toml, pyproject.toml (rebot also reads
rebot.toml).
confargs built-ins drive the feature: --config PATH, --no-config,
--profile NAME, --ignore-git. Named profiles ([tool.robot.profiles.ci])
are supported out of the box.
ROBOT_OPTIONS / REBOT_OPTIONS are still honoured (read by confargs).

# robot.toml
[tool.robot]
name = "My Suite"
loglevel = "DEBUG"
metadata = ["Owner:Bob"]

[tool.robot.profiles.ci]
output = "ci.xml"

robot tests/ now picks up that config; robot --name Other tests/ overrides
it; robot --no-config tests/ ignores it.

Config keys use the exact option name only (e.g. variablefile,
outputdir) — the case/hyphen leniency below applies to the command line, not
to config files.

Supported option forms (with examples)

Form	Example
Long + separate value	`--name My Suite`
Long + `=` value	`--name=My Suite`
Case-insensitive long name	`--Name`, `--OutputDir`
Hyphen-insensitive long name	`--variable-file` (= `--variablefile`)
Unique-prefix abbreviation	`--variab` (= `--variablefile`, if unambiguous)
Short + separate value	`-N My Suite`
Short + attached value	`-NMy Suite`
Repeated (multi) option	`-i tag1 -i tag2` / `--include tag1 --include tag2`
Boolean flag	`--dryrun`, `-X`
Combined short flags	`-XT` (= `--exitonfailure --timestampoutputs`)
Flag negation	`--no-dryrun`, `--nostatusrc`, `--no-statusrc`
Options terminator	`-- --not-an-option.robot`
Argument file (eager)	`-A args.txt`, `--argumentfile STDIN`

Short options stay case-sensitive by design (matching the legacy parser):
-V is --variablefile and -v is --variable; leniency applies to long
names only.

Compatibility with the legacy parser

Restored via confargs' opt-in features, so these keep working:

Legacy leniency	Example	Status
Case-insensitive long names	`--Name`, `--OutputDir`	✅ `cli_case_insensitive`
Hyphen-insensitive long names	`--tag-stat-link`, `--pre-run-modifier`	✅ `cli_ignore_hyphens`
Unique-prefix abbreviation	`--outp`, `--variab`, `--removek`	✅ `cli_allow_abbrev` (confargs 0.7; ambiguous prefixes raise)
`--no<flag>` negation (no dash)	`--nostatusrc`	✅ (both `--nostatusrc` and `--no-statusrc`)
Abbreviated joined negation	`--nostat` (= `--nostatusrc`)	✅ (`cli_allow_abbrev` + `cli_ignore_hyphens`, confargs 0.8)

Still intentionally dropped (the only user-visible behaviour changes):

Legacy leniency	Old	New
Second help alias `-?`	`-?`	use `-h` / `--help`

Everything else — option names, short flags (incl. -. for --dotted),
value/multi/flag semantics, defaults, --help text (the full USAGE is passed
through verbatim, footer included), --version, exit codes, data-source
globbing, ROBOT_OPTIONS — is unchanged.

Tests

Legacy utest/utils/test_argumentparser.py kept pristine (libdoc/testdoc
path unchanged).
New utest/utils/test_confargsparser.py (20 tests) covers value/multi/flag
parsing, = syntax, shorts, --no- negation, case-/hyphen-insensitive long
names, joined/cased negation (--nostatusrc, --No-DryRun), case-sensitive
shorts, --help/--version → Information, arg-limit errors,
unknown-option → DataError, internal keys not leaking, validator hook, and
rebot-specific options.
Full unit suite green: 2417 tests.
Acceptance tests (atest/robot/cli, 460 tests) run against confargs 0.8:
456 pass, 4 fail. All 4 remaining failures are environmental, not
caused by this change (Console.Non Ascii.* and Argument File.Argument file with non-ASCII characters — Windows-console mojibake on a non-UTF-8 codepage;
they pass on the Linux CI runners). The argument-file BOM, # expandvars:
pragma and abbreviated-joined-negation failures were all fixed by confargs
0.8 (MarketSquare/confargs#40), and the obsolete
Shortening --argumentfile is not possible atest was removed.

Manual smoke tests: robot/rebot --version/--help, real suite
execution, config-only vs CLI-override vs --no-config, -A argument files.
Lint/format: ruff + isort + black applied to changed files.

TODO / open questions

Python floor raised to 3.10. confargs requires Python 3.10+, so
python_requires, the trove classifiers and the CI matrices (unit +
acceptance) were updated to drop 3.8/3.9. confargs was also added to
utest/requirements.txt and atest/requirements-run.txt (used by the test
workflows, which run from source without pip install .). This floor bump is
a required consequence of adopting confargs and needs project sign-off.
Case-/hyphen-insensitive long names and unique-prefix abbreviation
restored via confargs' opt-in cli_case_insensitive / cli_ignore_hyphens
(0.6) and cli_allow_abbrev (0.7) toggles, so the CLI stays backwards
compatible without any robot-side canonicalisation.
libdoc / testdoc still use the legacy ArgumentParser. Migrate them
too, or keep the two parsers side by side long-term?
Argument-file BOM handling. confargs 0.8 reads argument files as
utf-8-sig, so a leading UTF-8 BOM is stripped
(MarketSquare/confargs#40).
Argument-file # expandvars: pragma is now supported by confargs 0.8
(${VAR} / ${VAR=default} expansion with RF-compatible error messages when
the pragma is present).
Abbreviated joined negation (--nostat for --nostatusrc) now works:
confargs 0.8 composes cli_allow_abbrev with the joined --no<flag> form.
Shortening --argumentfile is not possible atest removed — abbreviation
makes shortening work, so the test's premise is obsolete.
Programmatic API (robot.run() / rebot()) keyword names are unchanged
(e.g. outputdir, loglevel, variablefile), matching the user guide — a
readability rename was considered but rejected to avoid breaking that API.
Decide whether config discovery should also consider RF's existing
conventions / documented search paths.

Copilot

Pull request overview

This draft replaces Robot Framework’s internal getopt-based CLI parsing with the confargs resolution engine, enabling TOML-based configuration file support (e.g., robot.toml / pyproject.toml) while aiming to preserve existing CLI behavior and output.

Changes:

Swapped the core argument parsing/resolution to confargs.ConfigurationProcessor, keeping Robot’s usage-string-driven option introspection intact.
Added TOML configuration file discovery/processing and precedence (CLI > env > config > defaults).
Added unit tests covering basic config-file behavior and added a runtime dependency on confargs.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
`src/robot/utils/argumentparser.py`	Replaces getopt parsing with confargs + canonicalization layer and config-file support.
`utest/utils/test_argumentparser.py`	Adds unit tests for configuration file reading and precedence.
`setup.py`	Adds `confargs>=0.5` as a runtime dependency.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

+    def __init__(
+        self,
+        config,
+        usage,
+        name=None,
+        version=None,
+        arg_limits=None,
+        validator=None,
+        env_options=None,
+    ):
+        if not usage:
+            raise FrameworkError("Usage cannot be empty")
+        self._config = config
+        self._usage = usage
+        self.name = name or usage.splitlines()[0].split(" -- ")[0].strip()
+        self.version = version or get_full_version()
+        self._arg_limit_validator = ArgLimitValidator(arg_limits)
+        self._validator = validator
+        # ``env_options`` (ROBOT_OPTIONS / REBOT_OPTIONS) is read by confargs
+        # itself via the ``options_env_var`` class attribute on the config.
+


Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Suppressed comments (1)

src/robot/utils/confargsparser.py:76

env_options is accepted (and always passed from Application) but currently ignored, which makes Application(env_options=...) a no-op when using ConfargsParser. To preserve the legacy contract and avoid silent mismatches, wire env_options into the confargs config (or validate it).

        self._config = config
        self._usage = usage
        self.name = name or usage.splitlines()[0].split(" -- ")[0].strip()
        self.version = version or get_full_version()
        self._arg_limit_validator = ArgLimitValidator(arg_limits)

+Every value option defaults to ``None`` and every repeatable option to an empty
+list so that options the user did not give are filtered out before reaching the
+settings objects, which then apply their own defaults -- keeping behaviour
+identical to the legacy parser.


+def parser(config=RobotArgs, arg_limits=(1,), validator=None):
+    return ConfargsParser(
+        config,
+        USAGE,
+        arg_limits=arg_limits,
+        validator=validator,
+        env_options=None,
+    )


Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Suppressed comments (1)

src/robot/utils/confargsparser.py:69

env_options is accepted (and passed from Application) but not actually used by ConfargsParser (it’s only mentioned in a comment). This is easy to misconfigure for any future Application(..., config=...) consumers who expect env_options= to have an effect. Consider either (1) removing env_options from ConfargsParser and not passing it from Application, or (2) validating that env_options matches the config’s options_env_var and raising a clear error if not.

    def __init__(
        self,
        config,
        usage,
        name=None,
        version=None,
        arg_limits=None,
        validator=None,
        env_options=None,
    ):

+            self._ap = ConfargsParser(
+                config,
+                usage,
+                name,
+                version,
+                arg_limits,
+                self.validate,
+                env_options,
+            )


+            namespace = ConfigurationProcessor(
+                self._config,
+                argv=args,
+                environ=None,
+                cwd=Path.cwd(),
+            ).process()


Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Suppressed comments (1)

src/robot/utils/confargsparser.py:96

New functionality here relies on confargs merging sources (CLI > env var > config file). There are currently no unit tests exercising (1) ROBOT_OPTIONS/REBOT_OPTIONS env var ingestion/precedence and (2) config-file discovery/precedence (robot.toml/pyproject.toml, --no-config, --config, profiles). Adding focused tests would help ensure the behavior stays compatible with the legacy parser and matches the PR’s precedence guarantees.

        args = [system_decode(a) for a in args]
        try:
            namespace = ConfigurationProcessor(
                self._config,
                argv=args,
                environ=None,
                cwd=Path.cwd(),
            ).process()

Copilot

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

src/robot/utils/confargsparser.py:95

ConfigurationProcessor is currently called with environ=None, while Application still passes env_options and the PR description says ROBOT_OPTIONS/REBOT_OPTIONS remain supported. To make env-var handling unambiguous (and avoid accidentally disabling it if None means "no environment" in confargs), pass os.environ explicitly (or drop the override) and consider either using env_options or removing it from the constructor to avoid a misleading API.

            namespace = ConfigurationProcessor(
                self._config,
                argv=args,
                environ=None,
                cwd=Path.cwd(),

src/robot/conf/arguments.py:183

cli_allow_abbrev is enabled for rebot as well. This conflicts with the PR description's statement that unique-prefix long-option abbreviations are intentionally dropped; please align the implementation and the documented compatibility expectations.

    cli_case_insensitive = True
    cli_ignore_hyphens = True
    cli_allow_abbrev = True

Copilot

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

src/robot/utils/confargsparser.py:69

ConfargsParser.__init__() accepts env_options (and Application passes it), but the value is currently ignored. This creates a silent mismatch risk if the config’s options_env_var differs (or isn’t set), and it diverges from ArgumentParser where env_options directly controls env var parsing.

        arg_limits=None,
        validator=None,
        env_options=None,
    ):

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

src/robot/utils/confargsparser.py:80

env_options is accepted by ConfargsParser.__init__ (and is passed in from Application), but it is currently ignored. This creates a silent mismatch with ArgumentParser, where env_options controls which env var is consulted, and it can also hide configuration mistakes if env_options differs from config.options_env_var.

Either remove this parameter entirely for the confargs-backed path, or validate that it matches the ArgConfig’s options_env_var to avoid silently ignoring the caller’s intent.

    def __init__(
        self,
        config,
        usage,
        name=None,
        version=None,
        arg_limits=None,
        validator=None,
        env_options=None,
    ):
        if not usage:
            raise FrameworkError("Usage cannot be empty")
        self._config = config
        self._usage = usage
        self.name = name or usage.splitlines()[0].split(" -- ")[0].strip()
        self.version = version or get_full_version()
        self._arg_limit_validator = ArgLimitValidator(arg_limits)
        self._validator = validator
        # ``env_options`` (ROBOT_OPTIONS / REBOT_OPTIONS) is read by confargs
        # itself via the ``options_env_var`` class attribute on the config.

+    # --- Positional arguments ----------------------------------------------
+    data_sources: list[str] = argument(name="data-sources", nargs="*")
+


Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Suppressed comments (1)

src/robot/utils/confargsparser.py:76

env_options is accepted (and Application passes it) but it currently has no effect: config.options_env_var is never validated/overridden, so a mismatch would be silently ignored. Either validate that env_options matches config.options_env_var or derive a wrapper config that sets options_env_var from env_options to keep the parser adapter contract accurate.

        self._config = config
        self._usage = usage
        self.name = name or usage.splitlines()[0].split(" -- ")[0].strip()
        self.version = version or get_full_version()
        self._arg_limit_validator = ArgLimitValidator(arg_limits)

+        if config is not None:
+            self._ap = ConfargsParser(
+                config,
+                usage,
+                name,
+                version,
+                arg_limits,
+                self.validate,
+                env_options,
+            )
+        else:


+        if value.upper() == "STDIN":
+            return split_argument_file(sys.stdin.read())
+        return read_argument_file(value)


Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/robot/utils/application.py:46

When config is provided, Application.__init__ still accepts **auto_options but silently ignores them (they’re only forwarded to ArgumentParser). This can hide mistakes like auto_help=False having no effect with the confargs-based parser. Consider failing fast when auto_options are passed together with config (or add equivalent support in ConfargsParser).

        if config is not None:
            self._ap = ConfargsParser(

setup.py:78

PR description states setup.py adds a confargs>=0.7 dependency, but the code pins confargs>=0.8 (and test requirements also use >=0.8). Please align the PR description with the actual minimum version (or adjust the minimum if 0.8 features aren’t required).

    install_requires=[
        # Declarative CLI parsing and configuration-file support. confargs
        # requires Python 3.10+, which is why Robot Framework's minimum
        # supported Python version is raised to 3.10 in this change.
        "confargs>=0.8",
    ],

…port Replace the getopt-based command-line parsing of the `robot` and `rebot` tools with the declarative confargs library, and add configuration-file support (addresses robotframework#5337). The option set of each tool is now declared explicitly as a confargs `ArgConfig` subclass (`RobotArgs` / `RebotArgs` in `robot.conf.arguments`), and a thin `ConfargsParser` (`robot.utils.confargsparser`) adapts confargs to the existing `Application` parsing contract (`parse_args` -> options dict + globbed data sources, `Information` for `--help`/`--version`, `DataError` on failure). `Application` gained an optional `config=` parameter selecting the new parser; `libdoc`/`testdoc` keep using the legacy `ArgumentParser`. Configuration is merged with precedence: command line > environment variables > config file > option default. Config files are `[tool.robot]` / `[tool.rebot]` tables discovered upward from the working directory (and the user config dir), with `--config`, `--no-config`, `--profile` and `--ignore-git` controls provided by confargs. Behaviour of value/multi/flag options and their defaults is preserved so the downstream `RobotSettings`/`RebotSettings` defaulting is unchanged. Options now use their canonical spelling only: names are no longer case- or hyphen-insensitive and cannot be abbreviated, and boolean flags negate with `--no-<name>` (e.g. `--no-statusrc` instead of `--nostatusrc`). See the pull request description for the full migration notes and remaining TODOs. Co-authored-by: Copilot <[email protected]>

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Suppressed comments (2)

src/robot/utils/confargsparser.py:80

env_options is accepted by ConfargsParser.__init__ (and is always passed by Application), but it currently has no effect: confargs reads the env var name from config.options_env_var instead. This makes Application(..., config=..., env_options=...) behave unexpectedly if the caller passes a different env var name. Either validate/raise on mismatch or adapt the config used by confargs so env_options is honored.

    def __init__(
        self,
        config,
        usage,
        name=None,
        version=None,
        arg_limits=None,
        validator=None,
        env_options=None,
    ):
        if not usage:
            raise FrameworkError("Usage cannot be empty")
        self._config = config
        self._usage = usage
        self.name = name or usage.splitlines()[0].split(" -- ")[0].strip()
        self.version = version or get_full_version()
        self._arg_limit_validator = ArgLimitValidator(arg_limits)
        self._validator = validator
        # ``env_options`` (ROBOT_OPTIONS / REBOT_OPTIONS) is read by confargs
        # itself via the ``options_env_var`` class attribute on the config.

setup.py:78

install_requires requires confargs>=0.9, but this PR’s own test environments install confargs >= 0.8 (see utest/requirements.txt and atest/requirements-run.txt). This mismatch can let CI run with 0.8 while released installs require 0.9 (or vice versa), causing version-dependent behavior differences (CLI parsing / error messages). Align the minimum confargs version across runtime + test requirements (likely >=0.8 given the PR notes).

    python_requires=">=3.10",
    install_requires=[
        # Declarative CLI parsing and configuration-file support. confargs
        # requires Python 3.10+, which is why Robot Framework's minimum
        # supported Python version is raised to 3.10 in this change.
        "confargs>=0.9",
    ],

+        except Exit as exit_signal:
+            # confargs raises ``Exit`` as a clean-exit signal (e.g. after
+            # ``--show-completion`` / ``--install-completion`` have already
+            # printed their output). It is deliberately *not* an
+            # ``ArgConfigError``, so translate it into Robot Framework's own
+            # clean-exit path with a silent, success return code rather than
+            # letting it be reported as a usage error.
+            raise Information("", status_rc=bool(exit_signal.code))
+        except ArgConfigError as err:


+    def test_joined_and_cased_negation(self):
+        opts, _ = parser().parse_args(["--nostatusrc", "data.robot"])
+        assert_equal(opts["statusrc"], False)
+        opts, _ = parser().parse_args(["--No-DryRun", "data.robot"])
+        assert_equal(opts["dryrun"], False)


Copilot AI lite review requested due to automatic review settings August 31, 2026 08:53

Copilot started reviewing on behalf of bhirsz August 31, 2026 08:53 View session