argsman, cli: Allow options after non-option arguments (GNU-style) #35831

Allow options to be specified after non-option arguments in ParseParameters, matching GNU option parsing conventions (getopt_long style).
Currently in master, once the first non-dash argument was encountered, all subsequent arguments were collected verbatim into m_command. This meant -rpcwallet and similar options were silently ignored when placed after a command or its positional args. The same misspelled option before the command would be a clear error; after the command, it was silently treated as a positional argument — potentially triggering unintended RPC behaviour. With this change:

• Valid options after a command are stored in command_line_options exactly as if they appeared before the command.
• Unrecognized options after a command are always errors (no silent fallback to positional).
• A -- separator stops option processing; all subsequent arguments are treated as positional regardless of leading dashes.
• bitcoin-cli's CommandLineRPC is updated to derive its args vector from gArgs.GetCommand() rather than re-scanning raw argv.
• bitcoin-wallet benefits automatically: options such as -wallet placed after a command are now parsed correctly instead of being rejected as unexpected positional arguments.

<details> <summary><i><ins>Before and after:</ins></i> options after a command are now recognized...</summary>

<br>

-rpcwallet after the command and its positional args:

• Before (master) — -rpcwallet is silently ignored; request goes to the wrong wallet:

  $ bitcoin-cli -regtest -datadir=/tmp/btc listtransactions -rpcwallet=nonExistent                                                                           
  [                                                                                                                                                          
  ]                                                                                                                                                          
  

• After — correctly routes to the named wallet and fails with the expected error:

  $ bitcoin-cli -regtest -datadir=/tmp/btc listtransactions -rpcwallet=nonExistent                                                                           
  error code: -18                                                                                                                                            
  error message:                                                                                                                                             
  Requested wallet does not exist or is not loaded                                                                                                           
  

getaddressinfo with -rpcwallet appended:

• Before (master) — -rpcwallet becomes an extra positional arg; getaddressinfo errors with its usage string:

  $ bitcoin-cli -regtest -datadir=/tmp/btc getaddressinfo bcrt1q... -rpcwallet=nonExistent                                                                   
  error message:                                                                                                                                             
  getaddressinfo "address"                                                                                                                                   
  ...                                                                                                                                                        
  

• After — wallet is correctly selected:

  $ bitcoin-cli -regtest -datadir=/tmp/btc getaddressinfo bcrt1q... -rpcwallet=nonExistent                                                                   
  error code: -18                                                                                                                                            
  error message:                                                                                                                                             
  Requested wallet does not exist or is not loaded                                                                                                           
  

Multi-wallet: -rpcwallet no longer needs to come before the command:

• Before (master):

  $ bitcoin-cli -regtest -datadir=/tmp/btc listtransactions                                                                                                  
  error code: -19                                                                                                                                            
  error message:                                                                                                                                             
  ...specify the "-rpcwallet=<walletname>" option before the command...                                                                                      
  

  $ bitcoin-cli -regtest -datadir=/tmp/btc listtransactions -rpcwallet=mywallet                                                                              
  error code: -19   ← still fails; option after command was ignored                                                                                          
  error message:                                                                                                                                             
  ...specify the "-rpcwallet=<walletname>" option before the command...                                                                                      
  

• After:

  — error message updated:

  $ bitcoin-cli -regtest -datadir=/tmp/btc listtransactions
  error code: -19
  error message:  
  ...specify the "-rpcwallet=<walletname>" option before or after the command...
  

  — command executed successfully:

  $ bitcoin-cli -regtest -datadir=/tmp/btc listtransactions -rpcwallet=mywallet                                                                              
  [                                                                                                                                                          
    { "address": "bcrt1q...", "category": "immature", "amount": 50.00000000, ... }                                                                                 
  ]                                                                                                                                                          
  

</details>

<details> <summary><i><ins>Before and after:</ins></i> misspelled options and the <code>--</code> separator...</summary>

<br>

Misspelled option is now an error rather than a silent positional arg:

Before (master) — -rpcwalllet (note triple-l) silently absorbed as the label positional arg:

```                                                                                                                                                        
$ bitcoin-cli -regtest -datadir=/tmp/btc listtransactions <hash> -rpcwalllet=foo                                                                                   
{ ... }   ← result returned, -rpcwallet went unnoticed                                                                                                     
```                                                                                                                                                        
                                                                                                                                                           

After:

```                                                                                                                                                        
$ bitcoin-cli -regtest -datadir=/tmp/btc getblock <hash> -rpcwalllet=foo                                                                                   
error: Invalid parameter -rpcwalllet                                                                                                                       
```                                                                                                                                                        
                                                                                                                                                           

-- separator: pass a dash-prefixed string as a positional RPC argument:
$ bitcoin-cli -regtest -datadir=/tmp/btc somecommand -- -not-an-option

Everything after `--` is treated as a positional argument, so `-not-an-option` is passed to the RPC unchanged.

</details>

<details> <summary><i><ins>Before and after:</ins></i> <code>bitcoin-wallet</code> commands...</summary>

<br>

-wallet option placed after the command:

Before (master) — option treated as an unexpected positional arg:

    $ bitcoin-wallet -regtest -datadir=/tmp/btc create -wallet=myWallet
    Error: Additional arguments provided (-wallet=myWallet). Methods do not take arguments. Please refer to -help.

After:

    $ bitcoin-wallet -regtest -datadir=/tmp/btc create -wallet=myWallet
    Topping up keypool...
    Wallet info

    Name: myWallet
    Format: sqlite
    Descriptors: yes
    Encrypted: no
    HD (hd seed available): yes
    Keypool Size: 8000
    Transactions: 0
    Address Book: 0

</details>

Backwards compatibility: command lines where a dash-prefixed argument follows a non-dash argument will now be parsed as an option (if recognized) or an error (if not). Previously such arguments were silently collected as positional args. The -- separator can be used to pass arguments that begin with a dash as positional args.

<!--e57a25ab6845829454e8d69fc972939a-->

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

<!--006a51241073e994b41acfe9ec718e94-->

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35831.

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

See the guideline and AI policy for information on the review process.

If your review is incorrectly listed, please copy-paste <code>&lt;!--meta-tag:bot-skip--&gt;</code> into the comment that the bot should ignore.

<!--174a7506f384e20aa4161008e828411d-->

Conflicts

No conflicts as of last run.

<!--5faf32d7da4f0f540f40219e4f7537a3-->

LLM Linter (✨ experimental)

Possible places where named args for integral literals may be used (e.g. func(x, /*named_arg=*/0) in C++, and func(x, named_arg=0) in Python):

• self.nodes[0].cli('-generate', n5, 1000000, rpcwallet2).send_cli() in test/functional/interface_bitcoin_cli.py

^{2026-08-13 04:47:45}

<!--85328a0da195eb286784d51f73fa0af9-->

🚧 At least one of the CI tasks failed. _{Task test ancestor commits: https://github.com/bitcoin/bitcoin/actions/runs/30377658579/job/90337348515} _{LLM reason (✨ experimental): CI failed because the argsman_tests CTest suite failed (non-zero exit status 8 from “Errors while running CTest”).}

<details><summary>Hints</summary>

Try to run the tests locally, according to the documentation. However, a CI failure may still happen due to a number of reasons, for example:

• Possibly due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.

• A sanitizer issue, which can only be found by compiling with the sanitizer and running the affected test.

• An intermittent issue.

Leave a comment here, if you need help tracking down a confusing failure.

</details>

-<ins>Updates</ins>:

• Force-pushed to fix CI failures found after the initial push:
  • Windows (rpc_psbt.py) — positional arguments after a command (e.g. base64 PSBTs) were being lowercased, corrupting their values.
  • Windows (wallet_multiwallet.py) — paths starting with / after a command were being converted to - and parsed as options; fixed by only applying the Windows /→- conversion when there is no embedded slash (distinguishing /rpcwallet=foo from /bad/./path).
  • Alpine/musl (feature_pruning.py) — negative integers like -10 after a command were incorrectly treated as options instead of positional arguments.
• Also added a #ifdef WIN32 unit test covering Windows option syntax (/OPT=val, -OPTION) after a command, addressing a case raised in #33540.

Concept ACK.

-<ins>Updates</ins>:

• Simplified the is_number check: removed the opt_start variable, added a cmd_key[1] != '-' guard so --10 is now an error (consistent with pre-command behaviour). Intent is clearer: single dash + all digits => negative integer => positional arg.
• Added a missing SUCCESS test in util_AddCommand for a valid option specified after its command ({"x", "cmd2", "-opt1=foo"}), complementing the existing error case.
• Improved release notes: added bitcoin-wallet benefit, backwards compatibility note, reordered for clarity.
• Updated PR description: the multi-wallet "After" example now reflects that the WALLET_NOT_SPECIFIED error message reads "before or after the command".

:-)

-- is only recognized after the command, so using it before the first positional argument (for example, bitcoin-wallet -help -- create) incorrectly fails with Invalid parameter --.

In GNU-style parsing, -- should end option processing wherever it appears.

<details> <summary>Suggested fix</summary>

diff --git a/src/common/args.cpp b/src/common/args.cpp
index bdc01ce61c..be42134123 100644
--- a/src/common/args.cpp
+++ b/src/common/args.cpp
@@ -188,20 +188,28 @@ bool ArgsManager::ParseParameters(int argc, const char* const argv[], std::strin
         if (key.starts_with("-psn_")) continue;
 #endif
 
-        if (key == "-") break; //bitcoin-tx using stdin
+        bool options_ended{false};
+        if (key == "--") {
+            options_ended = true;
+            if (++i >= argc) break;
+            key = argv[i];
+        }
+        if (!options_ended && key == "-") break; //bitcoin-tx using stdin
         std::optional<std::string> val;
-        size_t is_index = key.find('=');
-        if (is_index != std::string::npos) {
-            val = key.substr(is_index + 1);
-            key.erase(is_index);
+        if (!options_ended) {
+            size_t is_index = key.find('=');
+            if (is_index != std::string::npos) {
+                val = key.substr(is_index + 1);
+                key.erase(is_index);
+            }
         }
 #ifdef WIN32
         key = ToLower(key);
-        if (key[0] == '/')
+        if (!options_ended && key[0] == '/')
             key[0] = '-';
 #endif
 
-        if (key[0] != '-') {
+        if (options_ended || key[0] != '-') {
             if (!m_accept_any_command && m_command.empty()) {
                 // The first non-dash arg is a registered command
                 std::optional<unsigned int> flags = GetArgFlags_(key);
@@ -211,6 +219,10 @@ bool ArgsManager::ParseParameters(int argc, const char* const argv[], std::strin
                 }
             }
             m_command.push_back(key);
+            if (options_ended) {
+                while (++i < argc) m_command.emplace_back(argv[i]);
+                break;
+            }
             while (++i < argc) {
                 std::string cmd_arg(argv[i]);
                 // "--" ends option processing; all subsequent args are positional
diff --git a/src/test/argsman_tests.cpp b/src/test/argsman_tests.cpp
index c8fad91c0c..4b9834a956 100644
--- a/src/test/argsman_tests.cpp
+++ b/src/test/argsman_tests.cpp
@@ -750,6 +750,39 @@ BOOST_AUTO_TEST_CASE(util_ParseParameters_gnu_style)
         BOOST_CHECK_EQUAL(cmd->args[1], "arg2");
     }
 
+    // "--" also ends option processing before the command.
+    {
+        TestArgsManager test;
+        test.SetupArgs({{"-opt", ArgsManager::ALLOW_ANY}});
+        test.AddCommand("cmd", "test command");
+        std::string error;
+        const char* argv[] = {"x", "--", "cmd", "-not-an-option", "arg2"};
+        BOOST_CHECK(test.ParseParameters(5, argv, error));
+        BOOST_CHECK(!test.IsArgSet("-opt"));
+        const auto cmd = test.GetCommand();
+        BOOST_REQUIRE(cmd);
+        BOOST_CHECK_EQUAL(cmd->command, "cmd");
+        BOOST_REQUIRE_EQUAL(cmd->args.size(), 2U);
+        BOOST_CHECK_EQUAL(cmd->args[0], "-not-an-option");
+        BOOST_CHECK_EQUAL(cmd->args[1], "arg2");
+    }
+
+    // Options before "--" are parsed, and the first positional argument after
+    // it may begin with a dash.
+    {
+        TestArgsManager test;
+        test.SetupArgs({{"-opt", ArgsManager::ALLOW_ANY}});
+        std::string error;
+        const char* argv[] = {"x", "-opt", "--", "-1"};
+        BOOST_CHECK(test.ParseParameters(4, argv, error));
+        BOOST_CHECK(test.IsArgSet("-opt"));
+        const auto cmd = test.GetCommand();
+        BOOST_REQUIRE(cmd);
+        BOOST_CHECK(cmd->command.empty());
+        BOOST_REQUIRE_EQUAL(cmd->args.size(), 1U);
+        BOOST_CHECK_EQUAL(cmd->args[0], "-1");
+    }
+
     // Options and positional args can be freely mixed after a command.
     {
         TestArgsManager test;

</details>

In the current PR code, on Windows, a post-command option such as /datadir=C:/bitcoin is mistaken for a positional argument because its value contains /.

<details> <summary>Suggested fix</summary>

diff --git a/src/common/args.cpp b/src/common/args.cpp
index bdc01ce61c..98c254cbaa 100644
--- a/src/common/args.cpp
+++ b/src/common/args.cpp
@@ -224,10 +224,12 @@ bool ArgsManager::ParseParameters(int argc, const char* const argv[], std::strin
 #ifdef WIN32
                 cmd_key = ToLower(cmd_key);
                 // Unlike pre-command args (options only), post-command args can be
-                // file paths. Only treat /foo as -foo when there is no embedded
-                // slash, which distinguishes Windows options (/rpcwallet=foo) from
-                // paths (/bad/./path). Bare '/' is excluded by the size > 1 check.
-                if (cmd_key.size() > 1 && cmd_key[0] == '/' && cmd_key.find('/', 1) == std::string::npos)
+                // file paths. Only check the option name for embedded slashes, as
+                // the option value itself may be a path. This distinguishes Windows
+                // options (/rpcwallet=dir/wallet) from paths (/bad/./path). Bare '/'
+                // is excluded by the size > 1 check.
+                const auto option_name{cmd_key.substr(0, cmd_key.find('='))};
+                if (option_name.size() > 1 && option_name[0] == '/' && option_name.find('/', 1) == std::string::npos)
                     cmd_key[0] = '-';
 #endif
                 // Negative integers (e.g. -10, -3) are positional args, not options.
diff --git a/src/test/argsman_tests.cpp b/src/test/argsman_tests.cpp
index c8fad91c0c..4744d20030 100644
--- a/src/test/argsman_tests.cpp
+++ b/src/test/argsman_tests.cpp
@@ -782,18 +782,20 @@ BOOST_AUTO_TEST_CASE(util_ParseParameters_gnu_style)
     }
 
 #ifdef WIN32
-    // On Windows, /option and -OPTION are equivalent to -option after a command.
+    // On Windows, slash options may have path values, while slash-prefixed paths
+    // remain positional arguments.
     {
         TestArgsManager test;
         test.SetupArgs({{"-opt", ArgsManager::ALLOW_ANY}});
         test.AddCommand("cmd", "test command");
         std::string error;
-        const char* argv[] = {"x", "cmd", "/OPT=val"};
-        BOOST_CHECK(test.ParseParameters(3, argv, error));
-        BOOST_CHECK_EQUAL(test.GetArg("-opt", ""), "val");
+        const char* argv[] = {"x", "cmd", "/OPT=C:/bitcoin", "/bad/./path"};
+        BOOST_CHECK(test.ParseParameters(4, argv, error));
+        BOOST_CHECK_EQUAL(test.GetArg("-opt", ""), "C:/bitcoin");
         const auto cmd = test.GetCommand();
         BOOST_REQUIRE(cmd);
-        BOOST_CHECK(cmd->args.empty());
+        BOOST_REQUIRE_EQUAL(cmd->args.size(), 1U);
+        BOOST_CHECK_EQUAL(cmd->args[0], "/bad/./path");
     }
 #endif
 }

</details>

A lone - after a command, such as in bitcoin-cli echo -, is incorrectly treated as an option and rejected with Invalid parameter -.

A single hyphen is a positional argument; an option must contain at least one character after it.

<details> <summary>Suggested fix</summary>

diff --git a/src/common/args.cpp b/src/common/args.cpp
index bdc01ce61c..b583938a1a 100644
--- a/src/common/args.cpp
+++ b/src/common/args.cpp
@@ -233,7 +233,7 @@ bool ArgsManager::ParseParameters(int argc, const char* const argv[], std::strin
                 // Negative integers (e.g. -10, -3) are positional args, not options.
                 bool is_number = cmd_key.size() > 1 && cmd_key[1] != '-' &&
                                  std::all_of(cmd_key.begin() + 1, cmd_key.end(), IsDigit);
-                bool is_option = !cmd_key.empty() && cmd_key[0] == '-' && !is_number;
+                bool is_option = cmd_key.size() > 1 && cmd_key[0] == '-' && !is_number;
                 if (is_option) {
                     // Options after a command are parsed the same way as options
                     // before a command — unrecognized options are always errors.
diff --git a/src/test/argsman_tests.cpp b/src/test/argsman_tests.cpp
index c8fad91c0c..a966606200 100644
--- a/src/test/argsman_tests.cpp
+++ b/src/test/argsman_tests.cpp
@@ -766,6 +766,20 @@ BOOST_AUTO_TEST_CASE(util_ParseParameters_gnu_style)
         BOOST_CHECK_EQUAL(cmd->args[1], "arg2");
     }
 
+    // A lone hyphen after a command is a positional argument, not an option.
+    {
+        TestArgsManager test;
+        test.SetupArgs({});
+        test.AddCommand("cmd", "test command");
+        std::string error;
+        const char* argv[] = {"x", "cmd", "-"};
+        BOOST_CHECK(test.ParseParameters(3, argv, error));
+        const auto cmd = test.GetCommand();
+        BOOST_REQUIRE(cmd);
+        BOOST_REQUIRE_EQUAL(cmd->args.size(), 1U);
+        BOOST_CHECK_EQUAL(cmd->args[0], "-");
+    }
+
     // Negative numbers after a command are positional args, not options.
     {
         TestArgsManager test;

</details>

In the current PR code, the parser correctly recognizes a trailing option like -json, but bitcoin-tx later rereads the original arguments and mistakenly treats -json as a transaction-editing command, causing error: unknown command.

The below fix makes bitcoin-tx use the already-filtered arguments while keeping its special - stdin behavior intact.

<details> <summary>Suggested fix</summary>

diff --git a/src/bitcoin-tx.cpp b/src/bitcoin-tx.cpp
index 017e8e1e6c..13ed7d77a8 100644
--- a/src/bitcoin-tx.cpp
+++ b/src/bitcoin-tx.cpp
@@ -797,35 +797,40 @@ static int CommandLineRawTx(int argc, char* argv[])
     std::string strPrint;
     int nRet = 0;
     try {
-        // Skip switches; Permit common stdin convention "-"
-        while (argc > 1 && IsSwitchChar(argv[1][0]) &&
-               (argv[1][1] != 0)) {
-            argc--;
-            argv++;
+        std::vector<std::string> args;
+        if (const auto command{gArgs.GetCommand()}) {
+            args = command->args;
+        } else {
+            // Parsing stops at "-", so fall back to argv to preserve stdin handling.
+            while (argc > 1 && IsSwitchChar(argv[1][0]) && argv[1][1] != 0) {
+                argc--;
+                argv++;
+            }
+            args.assign(argv + 1, argv + argc);
         }
 
         CMutableTransaction tx;
-        int startArg;
+        size_t startArg;
 
         if (!fCreateBlank) {
             // require at least one param
-            if (argc < 2)
+            if (args.empty())
                 throw std::runtime_error("too few parameters");
 
             // param: hex-encoded bitcoin transaction
-            std::string strHexTx(argv[1]);
+            std::string strHexTx(args[0]);
             if (strHexTx == "-")                 // "-" implies standard input
                 strHexTx = readStdin();
 
             if (!DecodeHexTx(tx, strHexTx, true))
                 throw std::runtime_error("invalid transaction encoding");
 
-            startArg = 2;
-        } else
             startArg = 1;
+        } else
+            startArg = 0;
 
-        for (int i = startArg; i < argc; i++) {
-            std::string arg = argv[i];
+        for (size_t i{startArg}; i < args.size(); ++i) {
+            const std::string& arg = args[i];
             std::string key, value;
             size_t eqpos = arg.find('=');
             if (eqpos == std::string::npos)
diff --git a/src/common/args.cpp b/src/common/args.cpp
index bdc01ce61c..655e35a9bd 100644
--- a/src/common/args.cpp
+++ b/src/common/args.cpp
@@ -210,7 +210,8 @@ bool ArgsManager::ParseParameters(int argc, const char* const argv[], std::strin
                     return false;
                 }
             }
-            m_command.push_back(key);
+            // Preserve unregistered commands verbatim; key may have been normalized above.
+            m_command.push_back(m_accept_any_command ? std::string{argv[i]} : key);
             while (++i < argc) {
                 std::string cmd_arg(argv[i]);
                 // "--" ends option processing; all subsequent args are positional
diff --git a/src/test/argsman_tests.cpp b/src/test/argsman_tests.cpp
index c8fad91c0c..415fe6747c 100644
--- a/src/test/argsman_tests.cpp
+++ b/src/test/argsman_tests.cpp
@@ -721,6 +721,19 @@ BOOST_AUTO_TEST_CASE(util_ParseParameters_gnu_style)
         BOOST_CHECK(cmd->args.empty());
     }
 
+    // The first positional argument is preserved exactly.
+    {
+        TestArgsManager test;
+        test.SetupArgs({});
+        std::string error;
+        const char* argv[] = {"x", "cmd=val"};
+        BOOST_CHECK(test.ParseParameters(2, argv, error));
+        const auto cmd = test.GetCommand();
+        BOOST_REQUIRE(cmd);
+        BOOST_REQUIRE_EQUAL(cmd->args.size(), 1U);
+        BOOST_CHECK_EQUAL(cmd->args[0], "cmd=val");
+    }
+
     // Unrecognized option after command is an error (not silently treated as positional).
     {
         TestArgsManager test;
diff --git a/test/functional/data/util/bitcoin-util-test.json b/test/functional/data/util/bitcoin-util-test.json
index 2aaffff4b5..41013e4c10 100644
--- a/test/functional/data/util/bitcoin-util-test.json
+++ b/test/functional/data/util/bitcoin-util-test.json
@@ -88,6 +88,11 @@
     "output_cmp": "blanktxv1.json",
     "description": "Creates a blank v1 transaction (output in json)"
   },
+  { "exec": "./bitcoin-tx",
+    "args": ["01000000000000000000", "-json"],
+    "output_cmp": "blanktxv1.json",
+    "description": "Parses an option after a transaction hex"
+  },
   { "exec": "./bitcoin-tx",
     "args": ["-"],
     "input": "blanktxv2.hex",

Approach ACK

The below fix makes bitcoin-tx use the already-filtered arguments while keeping its special - stdin behavior intact.

I didn't want to include any change into bitcoin-tx, as @ryanofsky suggested in previous #33540 but it this code is making the tool fail, I'll add the fix, thanks!

-<ins>Updates</ins>:

• Rebased.
• Restructured the PR into 3 commits (GNU parsing + 3 inner-loop fixes, -- before command, release notes);
• Fixed (inner loop, from @w0xlt reviews):
  • Windows: /OPT=C:/bitcoin after a command was mistakenly treated as positional because the embedded / in the value triggered the path check; now only the option name (before =) is checked;
  • Lone - after a command was misidentified as an option; now requires size > 1;
  • First positional argument verbatim preservation (cmd=val was being normalized by the outer =-split);
• Fixed: bitcoin-tx CommandLineRawTx now uses gArgs.GetCommand() instead of re-scanning raw argv, so GNU-style options after the transaction hex work correctly;
• Extended -- to also end option processing before the command (outer loop), not just after it.

(CI failures are not related)

ACK 67a8e5bea2e30c66d7f4eb33e8b124943c5d705f