First pass at new command line API

[andreww]

Only changes the documentation. For discussion.

Other things to do:

• [ ] Agree command line CLI
• [ ] Implement changes
• [ ] Make "cats" a runnable programme (via install process)
• [ ] Update other documentation
• [ ] Add tests!

[andreww]

I like the idea of a --format and a --dateformat option to give us flexibility and allow us to output in a sensible data exchange format. I imagine --scheduler could just be a shorthand wrapper to a combination of other arguments to make the output play nice with other tools.

[abhidg]

@andreww is this ready to merge?

[andreww]

@abhidg - no, afraid not. Thus far it's just changing the documentation to describe what we want to happen (and that still needs further update following @sadielbartholomew's suggestion). Actually writing the code to make cats behave like this is still something that needs doing (and I don't think we should merge the documentation until it describes the code).

[colinsauze]

I've just had a play around with this and have a few questions about the way it now behaves:

1. you can specify both --jobinfo and --config, which one takes precedence? The documentation doesn't say. Should we warn if both are specified?
2. --command seems to be optional, is this intentional? In the old CLI we piped commands to At but that doesn't work now, so isn't this the only way to invoke a command?
3. The README, "Use with Schedulers" pages of the documentation and animated gif example don't match the new CLI format.
4. Should it be possible to run without the --scheduler option (currently it is)?
5. Does anything accept the JSON format that you get when --format is specified? We used to have an At friendly format with a simple start date, this is probably redundant now we have the --scheduler option, but if it was going to be possible then another format for --format would seem to be the right way to achieve that (or should it be a --dateformat? I'm a little confused as to the differentiation between the two).

[abhidg]

I've just had a play around with this and have a few questions about the way it now behaves:

1. you can specify both --jobinfo and --config, which one takes precedence? The documentation doesn't say. Should we warn if both are specified?

They control different things: --config is for TDP and specifying CPU/GPU models as well as the API and location (currently only one API) and --jobinfo is job specific info like amount of memory or number of CPUs used.

2. --command seems to be optional, is this intentional? In the old CLI we piped commands to At but that doesn't work now, so isn't this the only way to invoke a command?

I am good either way. One reasoning for keeping it optional is if the user wants to use CATS just to get the optimal time and not schedule.

3. The README, "Use with Schedulers" pages of the documentation and animated gif example don't match the new CLI format.

Will update them once the CLI is locked in!

4. Should it be possible to run without the --scheduler option (currently it is)?

Matter of taste. I am fine either way. We could also default to --scheduler=at such that --scheduler is actually optional and require a command.

5. Does anything accept the JSON format that you get when --format is specified? We used to have an At friendly format with a simple start date, this is probably redundant now we have the --scheduler option, but if it was going to be possible then another format for --format would seem to be the right way to achieve that (or should it be a --dateformat? I'm a little confused as to the differentiation between the two).

Nothing accepts the JSON format, it is more for piping to something like jq, which we can give examples of -- the --dateformat option controls the date formatting within --format output. The old behaviour of piping a command to at can be expressed for example as:

ls | at -t $(cats --loc OX1 -d 5 --dateformat='%Y%m%d%H%M' --format=json | jq -r '.carbonIntensityOptimal.start'