From a2ac2232207563a302723f3c67ac9ce323cf285f Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Thu, 5 May 2022 16:53:02 -0700 Subject: [PATCH 1/4] Draft PR for CLI command feedback Signed-off-by: Steve Lasker --- specs/notation-cli.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 specs/notation-cli.md diff --git a/specs/notation-cli.md b/specs/notation-cli.md new file mode 100644 index 000000000..6e58af33f --- /dev/null +++ b/specs/notation-cli.md @@ -0,0 +1,36 @@ +# Notation CLI + +The following spec outlines the notation CLI. +The CLI commands are what's currently available in [notation v0.7.1-alpha.1](https://github.com/notaryproject/notation/releases/tag/v0.7.1-alpha.1) + + +```bash +notation help +NAME: + notation - Notation - Notary V2 + +USAGE: + notation [global options] command [command options] [arguments...] + +VERSION: + 0.0.0-SNAPSHOT-17c7607 + +AUTHOR: + CNCF Notary Project + +COMMANDS: + sign Signs artifacts + verify Verifies OCI Artifacts + push Push signature to remote + pull Pull signatures from remote + list, ls List signatures from remote + certificate, cert Manage certificates used for verification + key Manage keys used for signing + cache Manage signature cache + plugin Manage KMS plugins + help, h Shows a list of commands or help for one command + +GLOBAL OPTIONS: + --help, -h show help (default: false) + --version, -v print the version (default: false) +``` \ No newline at end of file From 8534682498fc41f5c42acaed1e6522c07e4be0fb Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Mon, 13 Jun 2022 16:56:21 -0700 Subject: [PATCH 2/4] Update CLI with existing sub commands Signed-off-by: Steve Lasker --- specs/notation-cli.md | 88 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/specs/notation-cli.md b/specs/notation-cli.md index 6e58af33f..a9014c04b 100644 --- a/specs/notation-cli.md +++ b/specs/notation-cli.md @@ -33,4 +33,92 @@ COMMANDS: GLOBAL OPTIONS: --help, -h show help (default: false) --version, -v print the version (default: false) +``` + +## sign + +```console + notation sign --help +NAME: + notation sign - Signs artifacts + +USAGE: + notation sign [command options] + +OPTIONS: + --key value, -k value signing key name + --key-file value signing key file + --cert-file value signing certificate file + --timestamp value, -t value timestamp the signed signature via the remote TSA + --expiry value, -e value expire duration (default: 0s) + --reference value, -r value original reference + --local, -l reference is a local file (default: false) + --output value, -o value write signature to a specific path + --push push after successful signing (default: true) + --push-reference value different remote to store signature + --username value, -u value username for generic remote access [$NOTATION_USERNAME] + --password value, -p value password for generic remote access [$NOTATION_PASSWORD] + --plain-http remote access via plain HTTP (default: false) + --media-type value specify the media type of the manifest read from file or stdin (default: "application/vnd.docker.distribution.manifest.v2+json") + --help, -h show help (default: false) +``` + +## verify + +```console +notation verify --help +NAME: + notation verify - Verifies OCI Artifacts + +USAGE: + notation verify [command options] + +OPTIONS: + --signature value, -s value, -f value signature files (accepts multiple inputs) + --cert value, -c value certificate names for verification (accepts multiple inputs) + --cert-file value certificate files for verification (accepts multiple inputs) + --pull pull remote signatures before verification (default: true) + --local, -l reference is a local file (default: false) + --username value, -u value username for generic remote access [$NOTATION_USERNAME] + --password value, -p value password for generic remote access [$NOTATION_PASSWORD] + --plain-http remote access via plain HTTP (default: false) + --media-type value specify the media type of the manifest read from file or stdin (default: "application/vnd.docker.distribution.manifest.v2+json") + --help, -h show help (default: false) +``` + +## push + +```console +notation push --help +NAME: + notation push - Push signature to remote + +USAGE: + notation push [command options] + +OPTIONS: + --signature value, -s value, -f value signature files (accepts multiple inputs) + --username value, -u value username for generic remote access [$NOTATION_USERNAME] + --password value, -p value password for generic remote access [$NOTATION_PASSWORD] + --plain-http remote access via plain HTTP (default: false) + --help, -h show help (default: false) +``` + +## pull + +```console +notation pull --help +NAME: + notation pull - Pull signatures from remote + +USAGE: + notation pull [command options] + +OPTIONS: + --strict pull the signature without lookup the manifest (default: false) + --output value, -o value write signature to a specific path + --username value, -u value username for generic remote access [$NOTATION_USERNAME] + --password value, -p value password for generic remote access [$NOTATION_PASSWORD] + --plain-http remote access via plain HTTP (default: false) + --help, -h show help (default: false) ``` \ No newline at end of file From 62377ef506410d38b886724a9acaf2c6b3cf55f1 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Mon, 13 Jun 2022 17:00:47 -0700 Subject: [PATCH 3/4] Add cli TOC Signed-off-by: Steve Lasker --- specs/notation-cli.md | 109 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) diff --git a/specs/notation-cli.md b/specs/notation-cli.md index a9014c04b..768ec35cc 100644 --- a/specs/notation-cli.md +++ b/specs/notation-cli.md @@ -3,6 +3,19 @@ The following spec outlines the notation CLI. The CLI commands are what's currently available in [notation v0.7.1-alpha.1](https://github.com/notaryproject/notation/releases/tag/v0.7.1-alpha.1) +## Table of Contents +- [notation](#notation) +- [sign](#sign): Signs artifacts +- [verify](#verify): Verifies OCI Artifacts +- [push](#push): Push signature to remote +- [pull](#pull): Pull signatures from remote +- [list](#list): List signatures from remote +- [certificate](#certificate): Manage certificates used for verification +- [key](#key): Manage keys used for signing +- [cache](#cache): Manage signature cache +- [plugin](#plugin): Manage KMS plugins + +## notation ```bash notation help @@ -121,4 +134,100 @@ OPTIONS: --password value, -p value password for generic remote access [$NOTATION_PASSWORD] --plain-http remote access via plain HTTP (default: false) --help, -h show help (default: false) +``` + +## list + +```console +notation list --help +NAME: + notation list - List signatures from remote + +USAGE: + notation list [command options] + +OPTIONS: + --username value, -u value username for generic remote access [$NOTATION_USERNAME] + --password value, -p value password for generic remote access [$NOTATION_PASSWORD] + --plain-http remote access via plain HTTP (default: false) + --help, -h show help (default: false) +``` + +## certificate + +```console +notation certificate --help +NAME: + notation certificate - Manage certificates used for verification + +USAGE: + notation certificate command [command options] [arguments...] + +COMMANDS: + add Add certificate to verification list + list, ls List certificates used for verification + remove, rm Remove certificate from the verification list + generate-test Generates a test RSA key and a corresponding self-signed certificate + help, h Shows a list of commands or help for one command + +OPTIONS: + --help, -h show help (default: false) +``` + +## key + +```console +notation key --help +NAME: + notation key - Manage keys used for signing + +USAGE: + notation key command [command options] [arguments...] + +COMMANDS: + add Add key to signing key list + update, set Update key in signing key list + list, ls List keys used for signing + remove, rm Remove key from signing key list + help, h Shows a list of commands or help for one command + +OPTIONS: + --help, -h show help (default: false) +``` +## cache + +```console + notation cache --help +NAME: + notation cache - Manage signature cache + +USAGE: + notation cache command [command options] [arguments...] + +COMMANDS: + list, ls List signatures in cache + prune Prune signature from cache + remove, rm Remove signature from cache + help, h Shows a list of commands or help for one command + +OPTIONS: + --help, -h show help (default: false) +``` + +## plugin + +```console +notation plugin --help +NAME: + notation plugin - Manage plugins + +USAGE: + notation plugin command [command options] [arguments...] + +COMMANDS: + list List registered plugins + help, h Shows a list of commands or help for one command + +OPTIONS: + --help, -h show help (default: false) ``` \ No newline at end of file From 0e5bb3f4af808fb26a49e1730905d0453b9a203f Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Fri, 1 Jul 2022 14:10:49 -0700 Subject: [PATCH 4/4] clarification for RC state Signed-off-by: Steve Lasker --- specs/notation-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/notation-cli.md b/specs/notation-cli.md index 768ec35cc..9b5c3706e 100644 --- a/specs/notation-cli.md +++ b/specs/notation-cli.md @@ -1,7 +1,7 @@ # Notation CLI The following spec outlines the notation CLI. -The CLI commands are what's currently available in [notation v0.7.1-alpha.1](https://github.com/notaryproject/notation/releases/tag/v0.7.1-alpha.1) +The CLI commands are what's currently available in [notation v0.7.1-alpha.1](https://github.com/notaryproject/notation/releases/tag/v0.7.1-alpha.1). The CLI experience in alpha.1 does not represent the final user experience, and CLI commands may have breaking changes before RC release as the CLI experience is finalized. ## Table of Contents - [notation](#notation)