What would you like to be added:

If we wish to encourage adoption of the OCI specification and tooling there are some usability issues that we should address. The purpose here is to improve the developer experience using the OCM CLI.

The cumulative effect of the improvements outlined here will streamline the ocm cli workflow and should mean that it is not necessary to use a Makefile in order to execute a simple series of ocm commands. This will encourage adoption and enable straightforward integration into build processes and scripted workflows.

• Component Initialization Process
• Target Directory
• Target Parameter
• Target Parameter
• Creating Resources, Sources & References
• Aliases & Inversions
• Unnamed Parameters
• Examples
• Surface important functionality

An example workflow with these changes incorporated could the as follows:

# initialise our ocm component
$ ocm init github.com/torvalds/cloud-native-kernel --version v1.0.0

# examine the resulting "workspace" and component archive
$ tree
.
├── .ocm/
│   ├── blobs/
│   └── component-descriptor.yaml
    
# create a resource for the podinfo container image
$ ocm create resource podinfo \
    --type ociImage \
    --version 6.2.0 \
    --access-type ociArtefact \
    --access-image-reference ghcr.io/stefanprodan/podinfo:6.2.0

# sign the component version locally with the supplied key
$ ocm sign --local --key ocm-private.key --name devsig

# transfer the component to the github container registry and also move the podinfo resource
$ ocm transfer component --with-resources ghcr.io/linux

# verify after transfer
$ ocm verify --repository ghcr.io/linux github.com/torvalds/cloud-native-kernel:v1.0.0 

# sign the component version remotely with the supplied key
$ ocm sign --key private.key --name ownersig github.com/torvalds/cloud-native-kernel:v1.0.0

Component Initialization Process

1 OCM initialisation workflow needs to be cleaner. An ocm init command should replace the ocm create componentarchive and be configurable with a single argument with options provided via named flags.

The current command is as follows:

ocm create componentarchive github.com/phoban01/ocm-example v1.0.0 phoban01 out

The proposed ocm init command could be used as follows:

For example:

ocm init github.com/phoban01/ocm-example --version v1.0.0

Note that it is not necessary to specify a target directory and additional flags can supply information about the provider or scheme. If not present they can be defaulted and extracted from the name.

Target Directory

The ocm init command should create an ocm content directory containing blobs and the component descriptor which is hidden from the user and doesn't pollute the working directory. By convention this could be called .ocm. This assumes the component archive working format would be a directory.

Target Parameter

The target parameter should not be required for each command, use .ocm by convention or specify with --target flag

Creating Resources, Sources & References

The ocm cli should enable generation of resources, sources or references. To create a new resource it should be possible to use a cli command rather than requiring to pass a configuration file:

ocm create resource app-config --type TarArchive \
    --input-type file \
    --input-path ./resources/config.tar.gz \
    --input-media-type text/yaml.tar.gz

It should also be possible to export the yaml to stdout for further editing:

ocm create resource app-config --type TarArchive \
    --input-type file \
    --input-path ./resources/config.tar.gz \
    --input-media-type text/yaml.tar.gz \
    --export > app-config.yaml
    
# ...edit app-config.yaml then add to component archive
ocm add resource app-config.yaml

Aliases & Inversions

There are currently far too many aliases for CLI commands.

For example:

ocm transfer componentversions | componentversion | cv | components | component | comps | comp | c

The ocm transfer componentarchive command can also be executed ocm componentarchive transfer. These types of inversions are unhelpful and confusing for users.

Unnamed parameters

The CLI makes frequent use of unnamed positional paramaters. The CLI should bias towards a single unnamed parameter; multiple unnamed parameters should be discouraged and instead optional arguments should be accompanied by flags.

For example:

ocm download resources <component> {<name>}

Should be:

ocm download resources <component> {--name <name>}

Examples

Many commands do not have a simple usage example. All should have a simple example and most should have more than one example.

Surface important functionality

The CLI does lots of useful and interesting things but these are not apparent to the user.

For example, to transfer resource content alongside the component descriptor it is necessary to use the following syntax:

 
ocm transfer component --resourcesByValue ghcr.io/phoban01//github.com/phoban01/wge-demo:v1.0.0 gcr.io/ocm-demo

This command should not have multiple aliases and should not obfuscate it's own utility using obscure flags.

A better alternative might be:

ocm transfer component --with-resources ghcr.io/phoban01/wge-demo:v1.0.0 gcr.io/ocm-demo

Likewise the ocm sign componentversion and ocm verify componentversion commands could be simplified to remove unnecessary subcommands.