feat: Food for thought for the new API CLI design [WIP]

[netmilk]

DISCLAIMER: This is not a final PR but a DRAFT to have conversation over.

I have transformed @barjin's initial proposal and notes from our session into a man page mock. It's just food for thought. There might be lots of factual discrepancies; this aims to get feedback as early as possible.

My primary adjustment is that I prefixed the slightly controversial run and actor namespaces to relieve the overload of the term "run" and to set clear expectations on the remote or local execution. The actor namespace is then dedicated solely to the actor-related commands as described in the actor-spec

I'm not super happy with the prefixes, but the other options are:

• break the actor run backward compatibility
• go for plurals runs, actors, datasets, etc.

[mtrunkat]

Just brainstorming -

What about using just an actor namespace instead of both actor and remote-actor but with Actor ID provided as a param or argument? Locally you don't have any Actor ID so it's clearly remote Actor when provided.

The same applies for the run below.

[mtrunkat]

Because otherwise you would need remote commands for storages too.

[netmilk]

Thank you! Yes! Let's brainstorm! :)

My biggest issues with the current design are:
1. No clear expectation setting on local or remote execution.
2. Overload of the term actor (runtime interaction vs. local execution vs. deployment mgmt).
3. Overload of the term run (verb vs noun, local vs remote, command vs namespace).
4. The run namespace isn't available due to backward compatibility. [1] There is a convention in the general CLI design that the namespace command returns help for the namespace apify run = apify run --help. Docker had to do the build andbuildx decision because of that.

The thought process behind the remote- prefix is that the actor namespace would be reserved for everything the SDKs would do in the literal scope of that single running instance of an Actor (runtime) that is being run locally or remotely - aligned with the apify/actor-spec and because 4. On the other hand, everything else – other than actor is remote and interacting with the platform.

You mentioned the 1. applies to the dataset and kvs, but I think there would be a clear expectation setting if the actor is the only namespace that does stuff locally. Should the CLI support creating, deleting, and listing local Datasets and KVS'es too? My impression is that it's covered by e.g. actor push-data

Options here are:

fix 1., 2.

• Would the deployment instead of remote-actor namespace work for you? remote-actor is synonymous with deployment to me. It would fix 1.
• Use actor for the remote deployments, and move everything (SDK-like) from the actor namespace to a namespace named sdk or runtime or this. (This isn't backward breaking because the 1.0.0 with the actor namespace replacing the $ apify actor:<cmd> hasn't been released yet afaik.)

fix 3.,4.

• Solution for removing the remote- prefix from remote-run because of 4. isn't going to be elegant:
  • go for plural runs, but that would break a convention of naming all the other namespaces, and we agreed on don't doing that int the design kick-off session
  • go for runx as mentioned in the problem statement
  • break conventions for the CLI design of subcommand (namespaces)

[1]

[B4nan]

This isn't backward breaking because the 1.0.0 with the actor namespace replacing the $ apify actor: hasn't been released yet afaik.)

This will be released as part of 0.20 soon (probably during this sprint). At least that's the plan, we could revert this bit if we want to.