Add CLI flags for Choria transport options

Add CLI flags for all Choria transport options so they can be passed on
the command line. CLI flags use a choria- prefix for clarity (e.g., --choria-config-file, --choria-ssl-ca) while
internal option keys remain unprefixed so inventory files stay clean
(e.g., choria: { config-file: /path }).

Rename choria-agent to task-agent since it only applies to task
execution. The CLI flag becomes --choria-task-agent.

New CLI flags:
  --choria-task-agent, --choria-config-file, --choria-ssl-ca,
  --choria-ssl-cert, --choria-ssl-key, --choria-collective,
  --choria-puppet-environment, --choria-rpc-timeout,
  --choria-task-timeout, --choria-command-timeout,
  --nats-servers, --nats-connection-timeout

The nats-* flags are not prefixed since they are already clearly
Choria-specific. Shared options (cleanup, tmpdir, host, interpreters)
are unchanged.

Author: nmburgan

docs/choria-transport-dev.md

@@ -359,7 +359,7 @@ One second provides reasonable responsiveness without excessive polling.
 
 ### Deterministic agent selection
 
-Agent selection for `run_task` is explicit via the `choria-agent` config
+Agent selection for `run_task` is explicit via the `task-agent` config
 option (default `bolt_tasks`). There is no automatic fallback between agents.
 If the selected agent is not available on a target, that target gets a clear
 error. This is simpler and more predictable than a try-and-fallback approach.

docs/choria-transport-plan.md

@@ -123,7 +123,7 @@ What shipped:
   cleanup
 - `run_task` via shell agent with support for all input methods (environment,
   stdin, both)
-- Deterministic agent selection via `choria-agent` config and `--choria-agent`
+- Deterministic agent selection via `task-agent` config and `--choria-task-agent`
   CLI flag (no automatic fallback between agents)
 - Batched shell polling via `shell.list` + `shell.statuses` for scalability
 - Platform-aware command builders for POSIX and Windows (PowerShell)

docs/choria-transport-testing.md

@@ -163,7 +163,7 @@ bolt_tasks agent to download. The server-side module paths are listed first
 so that OpenBolt reads the same module versions that the bolt_tasks agent will
 actually download from the server. The local `modules` directory comes last
 as a fallback for Puppetfile-installed dependencies. When using
-`--choria-agent shell`, OpenBolt uploads files directly, so local modules should
+`--choria-task-agent shell`, OpenBolt uploads files directly, so local modules should
 take precedence instead — put `modules` first or omit the server paths.
 
 Task helper dependencies like `puppetlabs-ruby_task_helper` must also be
@@ -483,10 +483,10 @@ Expected: Still fails with the shell agent error.
 
 ```bash
 # Force bolt_tasks (should work, same as default)
-bolt task run facts --targets nodeA.example.com --choria-agent bolt_tasks
+bolt task run facts --targets nodeA.example.com --choria-task-agent bolt_tasks
 
 # Force shell (should fail: not installed)
-bolt task run facts --targets nodeA.example.com --choria-agent shell
+bolt task run facts --targets nodeA.example.com --choria-task-agent shell
 ```
 
 Expected: First succeeds (or fails at download, not at agent detection).
@@ -553,7 +553,7 @@ default and both nodes have it.
 **run_task with local task (not on OpenVox/Puppet Server)**
 
 Test with a task that's NOT on the OpenVox/Puppet Server (a local custom task).
-Without `--choria-agent shell`, this will fail because bolt_tasks can't find
+Without `--choria-task-agent shell`, this will fail because bolt_tasks can't find
 the task on the OpenVox/Puppet Server:
 
 ```bash
@@ -570,12 +570,12 @@ bolt task run choria_test::hello --targets nodeA.example.com
 ```
 
 Expected: Fails with `bolt/choria-task-download-failed` and a message
-suggesting `--choria-agent shell`.
+suggesting `--choria-task-agent shell`.
 
-Now retry with `--choria-agent shell` (Node A has the shell agent):
+Now retry with `--choria-task-agent shell` (Node A has the shell agent):
 
 ```bash
-bolt task run choria_test::hello --targets nodeA.example.com --choria-agent shell
+bolt task run choria_test::hello --targets nodeA.example.com --choria-task-agent shell
 ```
 
 Expected: Succeeds via the shell agent.
@@ -584,10 +584,10 @@ Expected: Succeeds via the shell agent.
 
 ```bash
 # Use shell agent (Node A has it)
-bolt task run choria_test::hello --targets nodeA.example.com --choria-agent shell
+bolt task run choria_test::hello --targets nodeA.example.com --choria-task-agent shell
 
 # Use shell agent (Node B doesn't have it)
-bolt task run choria_test::hello --targets nodeB.example.com --choria-agent shell
+bolt task run choria_test::hello --targets nodeB.example.com --choria-task-agent shell
 ```
 
 Expected:
@@ -605,7 +605,7 @@ have both agents installed.
 bolt command run 'whoami' --targets nodeA.example.com,nodeB.example.com
 bolt script run /tmp/test_script.sh --targets nodeA.example.com,nodeB.example.com
 bolt task run facts --targets nodeA.example.com,nodeB.example.com
-bolt task run choria_test::hello --targets nodeA.example.com,nodeB.example.com --choria-agent shell
+bolt task run choria_test::hello --targets nodeA.example.com,nodeB.example.com --choria-task-agent shell
 ```
 
 All should succeed on both nodes.
@@ -728,7 +728,7 @@ OpenBolt caches agent lists per target for the transport's lifetime. Start a fre
 |-------------|----------------|-----------------|---------------------------|--------------------------------------|
 | run_command | agent error    | agent error     | works                     | works (shell)                        |
 | run_script  | agent error    | agent error     | works                     | works (shell)                        |
-| run_task    | no-agent error | works (bt)      | works (--choria-agent sh) | works (bt default, sh if configured) |
+| run_task    | no-agent error | works (bt)      | works (--choria-task-agent sh) | works (bt default, sh if configured) |
 | upload      | unsupported    | unsupported     | unsupported               | unsupported                          |
 | download    | unsupported    | unsupported     | unsupported               | unsupported                          |
 | connected?  | works          | works           | works                     | works                                |

docs/choria-transport.md

@@ -86,24 +86,37 @@ targets:
 
 ### Config option reference
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `choria-agent` | String | `bolt_tasks` | Agent for task execution: `bolt_tasks` or `shell`. Also available as `--choria-agent` CLI flag. |
-| `cleanup` | Boolean | `true` | Clean up temp directories after operations. Set to `false` for debugging. |
-| `collective` | String | (from Choria config file) | Choria collective to route messages through. Per-target. |
-| `command-timeout` | Integer | `60` | Seconds to wait for commands and scripts to complete. |
-| `config-file` | String | (auto-detected) | Path to a Choria/MCollective client config file. |
-| `host` | String | (from URI) | Target's Choria identity (FQDN). Overrides the hostname from the URI. |
-| `interpreters` | Hash | (none) | File extension to interpreter mapping (e.g., `{".rb": "/usr/bin/ruby"}`). |
-| `nats-connection-timeout` | Integer | `30` | Seconds to wait for the TCP connection to the NATS broker. |
-| `nats-servers` | String or Array | (from Choria config file) | NATS broker addresses. Overrides the config file. |
-| `puppet-environment` | String | `production` | Puppet environment for bolt_tasks file URIs. |
-| `rpc-timeout` | Integer | `30` | Seconds to wait for replies to individual RPC calls. |
-| `ssl-ca` | String | (from Choria config file) | CA certificate path for TLS. |
-| `ssl-cert` | String | (from Choria config file) | Client certificate path for TLS. |
-| `ssl-key` | String | (from Choria config file) | Client private key path for TLS. |
-| `task-timeout` | Integer | `300` | Seconds to wait for task execution to complete. |
-| `tmpdir` | String | `/tmp` or `C:\Windows\Temp` | Base path for temp directories on remote nodes. Must be absolute. |
+| Option | CLI Flag | Type | Default | Description |
+|--------|----------|------|---------|-------------|
+| `task-agent` | `--choria-task-agent` | String | `bolt_tasks` | Agent for task execution: `bolt_tasks` or `shell`. |
+| `cleanup` | `--cleanup` | Boolean | `true` | Clean up temp directories after operations. Set to `false` for debugging. |
+| `collective` | `--choria-collective` | String | (from config file) | Choria collective to route messages through. Per-target. |
+| `command-timeout` | `--choria-command-timeout` | Integer | `60` | Seconds to wait for commands and scripts to complete. |
+| `config-file` | `--choria-config-file` | String | (auto-detected) | Path to a Choria/MCollective client config file. |
+| `host` | | String | (from URI) | Target's Choria identity (FQDN). Overrides the hostname from the URI. |
+| `interpreters` | | Hash | (none) | File extension to interpreter mapping (e.g., `{".rb": "/usr/bin/ruby"}`). |
+| `nats-connection-timeout` | `--nats-connection-timeout` | Integer | `30` | Seconds to wait for the TCP connection to the NATS broker. |
+| `nats-servers` | `--nats-servers` | String or Array | (from config file) | NATS broker addresses in `nats://host:port` format (comma-separated for multiple). Multiple servers provide failover if a broker is unavailable. Overrides the config file. |
+| `puppet-environment` | `--choria-puppet-environment` | String | `production` | Puppet environment for bolt_tasks file URIs. |
+| `rpc-timeout` | `--choria-rpc-timeout` | Integer | `30` | Seconds to wait for replies to individual RPC calls. |
+| `ssl-ca` | `--choria-ssl-ca` | String | (from config file) | CA certificate path for TLS. |
+| `ssl-cert` | `--choria-ssl-cert` | String | (from config file) | Client certificate path for TLS. |
+| `ssl-key` | `--choria-ssl-key` | String | (from config file) | Client private key path for TLS. |
+| `task-timeout` | `--choria-task-timeout` | Integer | `300` | Seconds to wait for task execution to complete. |
+| `tmpdir` | `--tmpdir` | String | `/tmp` or `C:\Windows\Temp` | Base path for temp directories on remote nodes. Must be absolute. |
+
+**CLI flag precedence:** CLI flags provide default values that can be
+overridden by inventory-level config (per-group or per-target). For example,
+if a target has `collective: staging` in its inventory entry and
+`--choria-collective production` is passed on the CLI, the inventory value
+wins. For ad-hoc targets specified via `--targets` that aren't defined in an
+inventory file, CLI flags take full effect.
+
+For options that have corresponding values in the Choria config file
+(`nats-servers`, `ssl-ca`/`ssl-cert`/`ssl-key`, and `collective`), the full
+precedence from lowest to highest is: Choria config file < CLI flags <
+inventory. All other options use OpenBolt-level defaults and are not affected by
+the Choria config file.
 
 **Timeout hierarchy:** Three levels of timeout control different things:
 - `nats-connection-timeout` (30s): How long to wait for the initial TCP
@@ -160,7 +173,7 @@ Works with either the **bolt_tasks** or **shell** agent.
 bolt task run facts --targets node1.example.com
 
 # Use shell agent for local tasks not on the OpenVox/Puppet Server
-bolt task run my_project::check --targets node1.example.com --choria-agent shell
+bolt task run my_project::check --targets node1.example.com --choria-task-agent shell
 ```
 
 Agent selection is deterministic with no automatic fallback. If the selected
@@ -198,7 +211,7 @@ installed on target nodes.
 With the shell agent:
 - `run_command` and `run_script` work
 - `run_task` can use either agent (bolt_tasks by default, or shell with
-  `--choria-agent shell`)
+  `--choria-task-agent shell`)
 
 The shell agent DDL (required by the client library) is bundled with OpenBolt
 and loaded automatically. No client-side setup is needed.
@@ -270,8 +283,8 @@ modulepath:
 
 Server-side paths are listed first so that OpenBolt reads the same module versions
 that the bolt_tasks agent will download from the server. When using
-`--choria-agent shell`, OpenBolt uploads task files directly, so local modules
-should take precedence instead — put `modules` first or omit the server paths.
+`--choria-task-agent shell`, OpenBolt uploads task files directly, so local modules
+should take precedence instead -- put `modules` first or omit the server paths.
 
 OpenBolt also auto-injects its own internal paths (visible in `--log-level debug`
 output): `bolt-modules` is prepended, and `.modules` plus the gem's built-in
@@ -308,22 +321,22 @@ bolt/choria-task-download-failed: ... ruby_task_helper/files/task_helper.rb: 404
 ### Using the shell agent for tasks
 
 If a task is not available on the OpenVox/Puppet Server (e.g., it's a local project
-task), set `choria-agent` to `shell` to upload and execute it directly via
+task), set `task-agent` to `shell` to upload and execute it directly via
 the shell agent, bypassing the OpenVox/Puppet Server entirely:
 
 ```yaml
 # bolt-project.yaml
 choria:
-  choria-agent: shell
+  task-agent: shell
 ```
 
 Or per-invocation:
 
 ```bash
-bolt task run my_project::check --targets node1 --choria-agent shell
+bolt task run my_project::check --targets node1 --choria-task-agent shell
 ```
 
-When using `--choria-agent shell`, the OpenVox/Puppet Server requirement is bypassed
+When using `--choria-task-agent shell`, the OpenVox/Puppet Server requirement is bypassed
 entirely. OpenBolt uploads task files directly via the shell agent, so only the
 local modulepath matters.
 
@@ -338,7 +351,7 @@ local modulepath matters.
 
 3. **bolt_tasks requires an OpenVox/Puppet Server.** The bolt_tasks agent downloads
    task files from the OpenVox/Puppet Server. Tasks not served by the OpenVox/Puppet Server
-   will fail with an error suggesting `--choria-agent shell`.
+   will fail with an error suggesting `--choria-task-agent shell`.
 
 4. **No streaming output.** All output is returned on completion, not streamed
    incrementally.
@@ -354,7 +367,7 @@ local modulepath matters.
    after OpenBolt reports a timeout (bolt_tasks has no kill mechanism).
 
 8. **File size limit for shell agent uploads.** When using the shell agent
-   (`run_script`, `run_task` with `--choria-agent shell`), files are
+   (`run_script`, `run_task` with `--choria-task-agent shell`), files are
    base64-encoded and sent as RPC messages. The maximum file size is limited
    by the NATS max message size (default 1MB, roughly 750KB effective after
    base64 overhead). Increase `plugin.choria.network.client_max_payload` in

lib/bolt/bolt_option_parser.rb

@@ -13,6 +13,9 @@ class BoltOptionParser < OptionParser
                 run_context: %w[concurrency inventoryfile save-rerun cleanup puppetdb],
                 global_config_setters: PROJECT_PATHS + %w[modulepath],
                 transports: %w[transport connect-timeout tty native-ssh ssh-command copy-command],
+                choria: %w[config-file ssl-ca ssl-cert ssl-key collective
+                           puppet-environment rpc-timeout task-timeout command-timeout
+                           nats-servers nats-connection-timeout],
                 display: %w[format color verbose trace stream],
                 global: %w[help version log-level clear-cache] }.freeze
 
@@ -168,7 +171,7 @@ def get_help_text(subcommand, action = nil)
       when 'task'
         case action
         when 'run'
-          { flags: ACTION_OPTS + %w[params tmpdir noop choria-agent],
+          { flags: ACTION_OPTS + %w[params tmpdir noop task-agent],
             banner: TASK_RUN_HELP }
         when 'show'
           { flags: OPTIONS[:global] + OPTIONS[:global_config_setters] + %w[filter format],
@@ -1095,10 +1098,54 @@ def initialize(options)
       define('--tmpdir DIR', 'The directory to upload and execute temporary files on the target.') do |tmpdir|
         @options[:tmpdir] = tmpdir
       end
-      define('--choria-agent AGENT', %w[bolt_tasks shell],
+      define('--choria-task-agent AGENT', %w[bolt_tasks shell],
              "Which Choria agent to use for task execution (bolt_tasks, shell).",
              "Defaults to 'bolt_tasks'. Set to 'shell' for tasks not on the Puppet Server.") do |agent|
-        @options[:'choria-agent'] = agent
+        @options[:'task-agent'] = agent
+      end
+      define('--choria-config-file PATH',
+             'Path to a Choria/MCollective client configuration file.') do |path|
+        @options[:'config-file'] = path
+      end
+      define('--choria-ssl-ca PATH',
+             'CA certificate path for Choria TLS authentication.') do |path|
+        @options[:'ssl-ca'] = path
+      end
+      define('--choria-ssl-cert PATH',
+             'Client certificate path for Choria TLS authentication.') do |path|
+        @options[:'ssl-cert'] = path
+      end
+      define('--choria-ssl-key PATH',
+             'Client private key path for Choria TLS authentication.') do |path|
+        @options[:'ssl-key'] = path
+      end
+      define('--choria-collective NAME',
+             'Choria collective to route messages through.') do |name|
+        @options[:collective] = name
+      end
+      define('--choria-puppet-environment ENV',
+             "Puppet environment for bolt_tasks file downloads (default: 'production').") do |env|
+        @options[:'puppet-environment'] = env
+      end
+      define('--choria-rpc-timeout SECONDS', Integer,
+             'Seconds to wait for replies to individual Choria RPC calls (default: 30).') do |timeout|
+        @options[:'rpc-timeout'] = timeout
+      end
+      define('--choria-task-timeout SECONDS', Integer,
+             'Seconds to wait for task execution to complete (default: 300).') do |timeout|
+        @options[:'task-timeout'] = timeout
+      end
+      define('--choria-command-timeout SECONDS', Integer,
+             'Seconds to wait for commands and scripts to complete (default: 60).') do |timeout|
+        @options[:'command-timeout'] = timeout
+      end
+      define('--nats-servers SERVERS',
+             'NATS broker addresses in nats://host:port format (comma-separated for multiple).') do |servers|
+        @options[:'nats-servers'] = servers
+      end
+      define('--nats-connection-timeout SECONDS', Integer,
+             'Seconds to wait for the TCP connection to the NATS broker (default: 30).') do |timeout|
+        @options[:'nats-connection-timeout'] = timeout
       end
 
       separator "\n#{self.class.colorize(:cyan, 'Module options')}"

lib/bolt/config/transport/choria.rb

@@ -8,7 +8,6 @@ class Config
     module Transport
       class Choria < Base
         OPTIONS = %w[
-          choria-agent
           cleanup
           collective
           command-timeout
@@ -22,6 +21,7 @@ class Choria < Base
           ssl-ca
           ssl-cert
           ssl-key
+          task-agent
           task-timeout
           tmpdir
         ].sort.freeze
@@ -41,9 +41,9 @@ class Choria < Base
         private def validate
           super
 
-          if @config['choria-agent'] && !VALID_AGENTS.include?(@config['choria-agent'])
+          if @config['task-agent'] && !VALID_AGENTS.include?(@config['task-agent'])
             raise Bolt::ValidationError,
-                  "choria-agent must be one of #{VALID_AGENTS.join(', ')}, got '#{@config['choria-agent']}'"
+                  "task-agent must be one of #{VALID_AGENTS.join(', ')}, got '#{@config['task-agent']}'"
           end
 
           if @config['tmpdir'] && !absolute_path?(@config['tmpdir'])

lib/bolt/config/transport/options.rb

@@ -51,7 +51,7 @@ module Options
             _default: true,
             _example: false
           },
-          "choria-agent" => {
+          "task-agent" => {
             type: String,
             description: "Which Choria agent to use for task execution. Defaults to 'bolt_tasks' " \
                          "(downloads task files from a Puppet Server). Set to 'shell' for tasks " \