flag-add

Flag Add

Add a new CLI flag to a shipctl command end-to-end.

Inputs

• Command path (e.g., release, build cross, config set)
• Flag name (long form, e.g., --output-dir)
• Short alias (optional, e.g., -o)
• Type (string, bool, integer, path)
• Default value (or required if mandatory)
• Description (one-line, used in help text and docs)

Steps

1. Define the flag in the parser

   For Rust + clap:

   // In the relevant Args struct (src/cmd/{command}.rs)
   #[arg(long, short = '{alias}', default_value = "{default}",
         help = "{description}")]
   pub {flag_name}: {type},
   

   For Go + cobra:

   // In the relevant command file (cmd/{command}.go)
   cmd.Flags().{TypeVar}(&opts.{FlagName}, "{flag-name}", {default}, "{description}")
   

2. Wire the value into the command logic Pass the flag value through to whatever downstream call needs it. Verify the happy path compiles: cargo check / go build ./....

3. Update the help text Run shipctl {command} --help and confirm the flag appears with the correct description and default.

4. Add shell completions Regenerate completions (invoke manpage-sync skill, or manually):

   shipctl completions bash > completions/shipctl.bash
   shipctl completions zsh  > completions/_shipctl
   shipctl completions fish > completions/shipctl.fish
   

   Commit the updated completion files.

5. Update documentation Edit docs/reference/{command}.md:

   • Add a row to the Flags table: | --{flag-name} | {type} | {default} | {description} |
   • Add an Examples entry if the flag has a non-obvious use

6. Write or extend a test

   // tests/cmd_{command}.rs
   #[test]
   fn test_{flag_name}_flag() {
       let output = Command::cargo_bin("shipctl").unwrap()
           .arg("{command}")
           .arg("--{flag-name}").arg("{test-value}")
           .assert().success();
       // assert output contains expected value
   }