Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Baseline CLI reference for subsequent PRs on changes #171

Merged
merged 4 commits into from
Jul 1, 2022
Merged

Baseline CLI reference for subsequent PRs on changes #171

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a2ac223
Draft PR for CLI command feedback
SteveLasker May 5, 2022
8534682
Update CLI with existing sub commands
SteveLasker Jun 13, 2022
62377ef
Add cli TOC
SteveLasker Jun 14, 2022
0e5bb3f
clarification for RC state
SteveLasker Jul 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions specs/notation-cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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 refined.



```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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given that we decided to manage certificates using the trust policy defnition, should we drop
certificate and key

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also considering this usecase for local file with passpharse should we possibly have --passpharse as an option for sign. Are we planning to include sub command options for the CLI here?
notaryproject/roadmap#46

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to think through the initial experience and production experiences here.
What is the user experience to get started?
What is the user experience to add remote signed keys?
What is the user experience to add certs for verification?

Today, this can be accomplished with some straight-forward commands.
What will this experience look like in RC1?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

notation cert add is an alpha 1 command created before trust store and trust policy spec was finalized, and is not compatible with the spec. RC1 implements spec which uses trust store and trust policy instead of a global certificate list in config.json. This cert add command needs rename/changes along with possibly new commands to manage trust policy, which are currently not in scope for for RC1 release. RC1 is prioritizing core functionality, sign & verify commands, over usability of other features. We may update some other commands like key add or plugin list as part of ongoing work, but these are not blockers for RC1 release. Users can accomplish these scenarios by manually editing trust store, trust policy, config.json/signingkeys.json . We plan to add/update commands post RC1 and before GA release.

See examples here for how this needs to be configured for RC1 - trust store , trust policy.

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)
```