When subject artifact reference is not specified, error output of oras attach is confusing

[qweeah]

What happened in your environment?

Running below command with empty variable $BASE_IMAGE (and thus actually not specified):

> oras attach --artifact-type "application/vnd.openvex.vex+json" $BASE_IMAGE ./vex/python3.12.2.vex.json
Error: neither file nor annotation provided in the command
Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<layer_media_type>] [...]
To attach to an existing artifact, please provide files via argument or annotations via flag "--annotation". Run "oras attach -h" for more options and examples

The error message still "makes me think" because I specified a file and I don't want to add annotations.

What did you expect to happen?

The output error message should tell that the problem is with the image (or subject artifact).

How can we reproduce it?

Run oras attach without specifying any subject artifact reference.

What is the version of your ORAS CLI?

Version: 1.2.0
Go version: go1.22.3
Git commit: dcef719
Git tree state: clean

What is your OS environment?

20.04

Are you willing to submit PRs to fix it?

• Yes, I am willing to fix it.

[qweeah]

Technically, a valid artifact reference can also be a valid file path. When a user only provides one argument, it's hard to which of the below usages matches the real case:

• The subject reference is missing
• The to-be-attach file path is missing

Current(v1.2.0) error message handles the latter but the real use case is the former.

[qweeah]

IMHO, it's better to follow the practice suggested by CLI Guideline and make file reference specified by flags. E.g. The usage of oras attach should changed to

oras attach --artifact-type "application/vnd.openvex.vex+json" $BASE_IMAGE --file ./vex/python3.12.2.vex.json

Since it's breaking change, specifying file paths via argument should still be allowed but trigger deprecation warning.