CLI Output Guidelines for ORAS CLI

The goal is to outline a set of guidelines to improve the console output of the ORAS CLI. This uses the copy command cp as an example to call out issues.

Refer CLI Output Proposal for COPY with referrers

Framework :

Default Output
1. Useful
2. Concise
3. Human readable
Verbose Logging Ouput
1. This is user viewable feature
2. can be used by the user for troubleshooting the scenarios they would like to achieve.
3. Should focus on human readable output
Debug Output
Image Not Showing Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
–debug is ORAS developers only
1. Useful for application builders that are looking to fix a bug in ORAS
2. Consider showing internal CLI/API and variable states and possibly consider timing.
3. Ensure that there is a warning that clients should not take dependency of format or fields of DEBUG outputs.
4. Consider debug as exposed through environment variables :::note

This focuses on copycp but the general recommendation might be applicable for other commands.
Recommend each command have a proposal doc that is reviewed by maintainers or stake holders.

Verbose logging experience

Following curl and other tools as an example here -

-v is the only option that a CLI users should be using. By default verbose is output is visibible to standard out

Can be suppressed by redirection

Stdout will only include the actual outputs and not the verbose logs

Both stdout and vebose logs can be redirected as follow

Include warning in verbose and debug logs

Example of client showing that these are not stable.

Looking at ORAS cp

$ oras cp docker.io/library/hello-world:latest --platform linux/amd64 --to-oci-layout .
Copied [registry] docker.io/library/hello-world:latest => [oci-layout] .
Digest: sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4

Observations :

The information that is useful here is just the digest.
This is probably too concise.

Recommendataion:

Docker CLI outputs the layers and possibly keeping in line with that is my take.
Add info from verbose logs in the default output.

Current verbose output

$ oras cp docker.io/library/hello-world:latest --platform linux/amd64 \
    --to-oci-layout . \
    --verbose
Copying 2db29710123e application/vnd.docker.image.rootfs.diff.tar.gzip
Copying feb5d9fea6a5 application/vnd.docker.container.image.v1+json
Copied  2db29710123e application/vnd.docker.image.rootfs.diff.tar.gzip
Copied  feb5d9fea6a5 application/vnd.docker.container.image.v1+json
Copying f54a58bc1aac application/vnd.docker.distribution.manifest.v2+json
Copied  f54a58bc1aac application/vnd.docker.distribution.manifest.v2+json
Copied [registry] docker.io/library/hello-world:latest => [oci-layout] .
Digest: sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4

Observations:

This is more inline with what I consider as default output.
Usable and indicates the number of layers etc.

Expected output with –verbose

Proposal

--debug is not requred anymore
--detailed is not needed here or in other commands if present
Reduce the volume by removing redundant words like request/response in every log line
Remove quotations to align with regular outputs.

$ oras cp docker.io/library/hello-world:latest \
    --platform linux/amd64 --to-oci-layout . \
    --verbose
Request #0
> URI:  https://registry-1.docker.io/v2/library/hello-world/manifests/latest
> Method: GET
> Headers:
   Accept: application/vnd.docker.distribution.manifest.v2+json, application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json, application/vnd.oci.artifact.manifest.v1+json
   User-Agent: oras/1.0.0
Response #0
< Status: 401 Unauthorized
< Headers:
   Date: Tue, 04 Apr 2023 14:54:11 GMT
   Content-Length: 162
   Content-Type: application/json
   Docker-Distribution-Api-Version: registry/2.0
   Www-Authenticate: Bearer realm=\https://auth.docker.io/token\,service=\registry.docker.io\,scope=\repository:library/hello-world:pull\
   Strict-Transport-Security: max-age=31536000
   Docker-Ratelimit-Source: 4.194.235.164

...

Support redirection of verbose output to stderr

Consider the following example -v is shows the output the user but it can be redirect to 2>/dev/null

❯ curl -v https://bing.com
*   Trying 204.79.197.200:443...
* Connected to bing.com (204.79.197.200) port 443 (#0)
* ALPN: offers h2,http/1.1
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):

❯ curl -v https://bing.com 2>/dev/null
<html><head><title>Object moved</title></head><body>
<h2>Object moved to <a href="https://www.bing.com:443/?toWww=1&amp;redig=B44C4C1386F745A5831C7DBE82203C2C">here</a>.</h2>
</body></html>

Handling concurrency in verbose outputs

There are few options we can consdier for this.

Do nothing
Suffix > or < with an operation id like >[1]

toddysm

2023/04/04 22:44:15

Are we talking about logging or outputs from the commands? Outputs from the commands can be used for automation, piping into other commands etc. Output can also be user-friendly for purposes of the user to understand what happened. Logging on the other side can be used two-folds: for troubleshooting by end-user and for troubleshooting by the developer of the tool. (Edited)

2023/04/04 22:46:13

Verbose Logging

This is user viewable feature and can be used by the user for troubleshooting the scenarios they would like to achieve. (Edited)

Sajay Antony

2023/04/05 00:01:56

Used your comments to reword this .

2023/04/04 22:46:38

Debug Ou

This should be hidden from the end user. (Edited)

2023/04/05 00:03:38

This does sound interesting. Maybe we should make ORAS_DEBUG=1

Shiwei Zhang

2023/05/09 09:57:33

The `--debug` flag was inspired by the `az` CLI.

2023/05/09 09:57:37

--debug : Increase logging verbosity to show all debug logs.

2023/04/04 22:48:22

Maybe we want to add more diverse examples. Copying a deep hierarchy of artifacts is a good example . (Edited)

2023/04/05 00:04:14

I'm using this document as a framework going forward and apply this to other commands. Ideally would like to have independent docs with specs for each command.

2023/04/04 22:51:02

Default Output

Additional thing we need to think about is whether we optimize for human or for automation. Right now our outputs are not optimized for either. For example, I always need to specify `-o tree` because this is the most useful output for the `oras discover` for me as a human and `-o json` if I want to automate. The default output from the `oras discover` is not useful for either of those actors. (Edited)

2023/04/04 22:53:55

The information that is useful here is just the digest.

The question that I immediately will have is what "digest" this is - the originating image digest or the resulting? It is not clear. For copying deep hierarchy, there can be the following cases from user point of view: - Simple output: I want to know how may artifacts got copied as a summary - Detailed: I would like to know the details (like tag/digest) of each artifact that got copied (Edited)

2023/04/05 00:05:08

Refer this for copy proposal - https://hackmd.io/segG-CfnR7CVEQ1aagpvcg

2023/04/04 23:00:42

This is probably too concise.

Having a message like "Copied artifact with [tag] and [digest] from repo [A] to repo [B]. would be helpful for the user" For automation preserving this information will allow the automation to take action on each repo or the tag or the digest. For example, the next step for bot the user and the automation may be to sign the artifact. They need the above details to do so. Or attach something to that artifact. (Edited)

2023/04/04 23:03:22

Usable and indicates the number of layers etc.

Although the location for the layout is known, outputting it again may be useful. Also in automation it can be passed via async methods where you lose the environment details of this particular task. (Edited)

Feynman Zhou

2023/04/06 15:02:17

Recommend each command have a proposal doc that is reviewed by maintainers or stake holders.

Agree. There is a folder to store proposal of new features in ORAS: https://github.com/oras-project/oras/tree/main/docs/proposals and a CLI spec folder in Notation (Edited)

2023/04/06 18:47:59

Consider debug as exposed through environment variables :::note -

This would be a breaking change and can be 2.0 issue. But we can start introducing the environment variable support and deprecate the flag in 2.0. (Edited)

2023/04/04 22:45:29

I think this is what I meant with outputs above. This should also be used in two ways: 1. for human user benefit and 2. for automation (Edited)

2023/04/06 14:32:58

Should we differentia two types of target users/scenarios for the output? Typically, human and automation tool (Edited)

Billy Zha

2023/05/09 09:05:28

+1 human<=>terminal automation tool<=>non-terminal (Edited)

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`	在筆記中貼入程式碼
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.