Mark sq keyring filter experimental.

- Invoking it now requires the `--experimental` flag.  This is a
    template that we may use to introduce features into sq with a bit
    of a chance to stabilize it over time.

  - Fixes #455.

NEWS

@@ -124,6 +124,9 @@
    - `sq` now reads a configuration file that can be used to tweak a
      number of defaults, like the cipher suite to generate new keys,
      the set of key servers to query, and the cryptographic policy.
+   - The command `sq keyring filter` is now considered experimental
+     and may change in the future.  To acknowledge this, it has to be
+     invoked with the `--experimental` flag.
 
 * Changes in 0.39.0
 ** Notable changes

sq-subplot.md

@@ -628,7 +628,7 @@ given an installed sq
 when I run sq key generate --own-key --without-password --userid Alice --output alice.pgp --rev-cert alice.pgp.rev
 when I run sq key generate --own-key --without-password --userid Bob --output bob.pgp --rev-cert bob.pgp.rev
 when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp
-when I run sq keyring filter --to-cert ring.pgp --output filtered.pgp
+when I run sq keyring filter --experimental --to-cert ring.pgp --output filtered.pgp
 when I run sq inspect filtered.pgp
 then stdout contains "OpenPGP Certificate."
 then stdout doesn't contain "Transferable Secret Key."
@@ -646,7 +646,7 @@ given an installed sq
 when I run sq key generate --own-key --without-password --userid Alice --output alice.pgp --rev-cert alice.pgp.rev
 when I run sq key generate --own-key --without-password --userid Bob --output bob.pgp --rev-cert bob.pgp.rev
 when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp
-when I run sq keyring filter --to-cert ring.pgp
+when I run sq keyring filter --experimental --to-cert ring.pgp
 then stdout contains "-----BEGIN PGP PUBLIC KEY BLOCK-----"
 then stdout contains "-----END PGP PUBLIC KEY BLOCK-----"
 ~~~
@@ -659,7 +659,7 @@ criteria._
 ~~~scenario
 given an installed sq
 when I run sq key generate --own-key --without-password --userid Alice --userid Bob --output alice.pgp --rev-cert alice.pgp.rev
-when I run sq keyring filter --prune-certs --name Alice alice.pgp --output filtered.pgp
+when I run sq keyring filter --experimental --prune-certs --name Alice alice.pgp --output filtered.pgp
 when I run sq inspect filtered.pgp
 then stdout contains "Alice"
 then stdout doesn't contain "Bob"
@@ -675,7 +675,7 @@ given an installed sq
 when I run sq key generate --own-key --without-password --userid Alice --output alice.pgp --rev-cert alice.pgp.rev
 when I run sq key generate --own-key --without-password --userid Bob --output bob.pgp --rev-cert bob.pgp.rev
 when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp
-when I run sq keyring filter --userid Alice ring.pgp --output filtered.pgp
+when I run sq keyring filter --experimental --userid Alice ring.pgp --output filtered.pgp
 when I run sq inspect filtered.pgp
 then stdout contains "Alice"
 then stdout doesn't contain "Bob"
@@ -691,7 +691,7 @@ given an installed sq
 when I run sq key generate --own-key --without-password --userid Alice --output alice.pgp --rev-cert alice.pgp.rev
 when I run sq key generate --own-key --without-password --userid Bob --output bob.pgp --rev-cert bob.pgp.rev
 when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp
-when I run sq keyring filter --userid Alice --userid Bob ring.pgp --output filtered.pgp
+when I run sq keyring filter --experimental --userid Alice --userid Bob ring.pgp --output filtered.pgp
 when I run sq inspect filtered.pgp
 then stdout contains "Alice"
 then stdout contains "Bob"
@@ -707,7 +707,7 @@ given an installed sq
 when I run sq key generate --own-key --without-password --userid 'Alice <alice@example.com>' --output alice.pgp --rev-cert alice.pgp.rev
 when I run sq key generate --own-key --without-password --userid 'Bob <bob@example.com>' --output bob.pgp --rev-cert bob.pgp.rev
 when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp
-when I run sq keyring filter --name Alice ring.pgp --output filtered.pgp
+when I run sq keyring filter --experimental --name Alice ring.pgp --output filtered.pgp
 when I run sq inspect filtered.pgp
 then stdout contains "Alice"
 then stdout doesn't contain "Bob"
@@ -723,7 +723,7 @@ given an installed sq
 when I run sq key generate --own-key --without-password --userid 'Alice <alice@example.com>' --output alice.pgp --rev-cert alice.pgp.rev
 when I run sq key generate --own-key --without-password --userid 'Bob <bob@example.com>' --output bob.pgp --rev-cert bob.pgp.rev
 when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp
-when I run sq keyring filter --name Alice --name Bob ring.pgp --output filtered.pgp
+when I run sq keyring filter --experimental --name Alice --name Bob ring.pgp --output filtered.pgp
 when I run sq inspect filtered.pgp
 then stdout contains "Alice"
 then stdout contains "Bob"
@@ -739,7 +739,7 @@ given an installed sq
 when I run sq key generate --own-key --without-password --userid 'Alice <alice@example.com>' --output alice.pgp --rev-cert alice.pgp.rev
 when I run sq key generate --own-key --without-password --userid 'Bob <bob@sequoia-pgp.org>' --output bob.pgp --rev-cert bob.pgp.rev
 when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp
-when I run sq keyring filter --domain example.com ring.pgp --output filtered.pgp
+when I run sq keyring filter --experimental --domain example.com ring.pgp --output filtered.pgp
 when I run sq inspect filtered.pgp
 then stdout contains "Alice"
 then stdout doesn't contain "Bob"
@@ -755,7 +755,7 @@ given an installed sq
 when I run sq key generate --own-key --without-password --userid 'Alice <alice@example.com>' --output alice.pgp --rev-cert alice.pgp.rev
 when I run sq key generate --own-key --without-password --userid 'Bob <bob@sequoia-pgp.org>' --output bob.pgp --rev-cert bob.pgp.rev
 when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp
-when I run sq keyring filter --domain example.com --domain sequoia-pgp.org ring.pgp --output filtered.pgp
+when I run sq keyring filter --experimental --domain example.com --domain sequoia-pgp.org ring.pgp --output filtered.pgp
 when I run sq inspect filtered.pgp
 then stdout contains "Alice"
 then stdout contains "Bob"

src/cli/keyring.rs

@@ -61,10 +61,32 @@ If multiple predicates are given, they are or'ed, i.e., a key matches \
 if any of the predicates match.  To require all predicates to match, \
 chain multiple invocations of this command.  See EXAMPLES for \
 inspiration.
+
+Note: this command is considered experimental and may change in future \
+releases.  To acknowledge this, you must give the `--experimental` \
+flag when invoking this command.
 ",
     after_help = FILTER_EXAMPLES,
 )]
 pub struct FilterCommand {
+    #[clap(
+        long = "experimental",
+        required = true,
+        help = "Opt-in to using an experimental feature",
+        long_help = "\
+Opt-in to using an experimental feature
+
+This command is considered experimental and may change in future \
+releases.  To acknowledge this, you must give the `--experimental` \
+flag when invoking this command.
+
+In the future, we may stabilize this command.  When that happens, \
+`--experimental` will no longer be required, but will be ignored \
+silently.
+",
+    )]
+    pub _experimental: bool,
+
     #[clap(value_name = "FILE", help = "Read from FILE or stdin if omitted")]
     pub input: Vec<PathBuf>,
     #[clap(
@@ -166,6 +188,7 @@ const FILTER_EXAMPLES: Actions = Actions {
 Convert all keys to certificates (i.e. remove any secret key material).",
             command: &[
                 "sq", "keyring", "filter",
+                "--experimental",
                 "--to-cert",
                 "certs.pgp",
             ],
@@ -176,6 +199,7 @@ Convert all keys to certificates (i.e. remove any secret key material).",
 Get all certificates with a user ID on example.org.",
             command: &[
                 "sq", "keyring", "filter",
+                "--experimental",
                 "--domain=example.org",
                 "certs.pgp",
             ],
@@ -186,6 +210,7 @@ Get all certificates with a user ID on example.org.",
 Get all certificates with a user ID on example.org or example.net.",
             command: &[
                 "sq", "keyring", "filter",
+                "--experimental",
                 "--domain=example.org",
                 "--domain=example.net",
                 "certs.pgp",
@@ -197,6 +222,7 @@ Get all certificates with a user ID on example.org or example.net.",
 Get all certificates with a name user ID matching Romeo.",
             command: &[
                 "sq", "keyring", "filter",
+                "--experimental",
                 "--name=Romeo",
                 "certs.pgp",
             ],
@@ -207,9 +233,11 @@ Get all certificates with a name user ID matching Romeo.",
 Get all certificates with a name user ID matching Romeo on example.org.",
             command: &[
                 "sq", "keyring", "filter",
+                "--experimental",
                 "--domain=example.org",
                 "certs.pgp",
                 "|", "sq", "keyring", "filter",
+                "--experimental",
                 "--name=Romeo",
             ],
         }),
@@ -219,6 +247,7 @@ Get all certificates with a name user ID matching Romeo on example.org.",
 Get all certificates with a user ID on example.org, pruning other user IDs.",
             command: &[
                 "sq", "keyring", "filter",
+                "--experimental",
                 "--domain=example.org",
                 "--prune-certs",
                 "certs.pgp",
@@ -325,6 +354,7 @@ const LIST_EXAMPLES: Actions = Actions {
 List all certificates with a user ID on example.org.",
             command: &[
                 "sq", "keyring", "filter",
+                "--experimental",
                 "--domain=example.org",
                 "certs.pgp",
                 "|", "sq", "keyring", "list",

tests/integration/sq_keyring_filter.rs

@@ -69,6 +69,7 @@ fn filter(sq: &Sq, args: &[&str]) -> Vec<Cert> {
     let mut cmd = sq.command();
     cmd.arg("keyring")
         .arg("filter")
+        .arg("--experimental")
         .arg("--output=-")
         .args(args)
         .arg("keys.pgp");