diff options
| -rw-r--r-- | proposals/2020_client_cli.md | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/proposals/2020_client_cli.md b/proposals/2020_client_cli.md new file mode 100644 index 00000000..2a0c8fa1 --- /dev/null +++ b/proposals/2020_client_cli.md @@ -0,0 +1,124 @@ + +status: prototyping, side-project + + +Fatcat CLI Client +=================== + + fatcat get release_awuvsvwrwzev7jcljyo34r6gem + fatcat get --toml release_awuvsvwrwzev7jcljyo34r6gem + + fatcat search containers "elife" + => pretty prints in terminal/interactive; JSON rows in ES schema for non-interactive + => limit, offset + +Editing commands: + + fatcat editgroup new + + fatcat editgroup list + fatcat eg list + + fatcat update container_tupsi5ep7bhhraup4irzk6tpuy publisher="Taylor and Francis" + => prints URL of revision, and mentioned editgroup id + + fatcat get container_tupsi5ep7bhhraup4irzk6tpuy --toml > wip.toml + => --expand files, --hide as args or "expand==files"? + # edit wip.toml + fatcat update container_tupsi5ep7bhhraup4irzk6tpuy --toml < wip.toml + + fatcat delete release_awuvsvwrwzev7jcljyo34r6gem + + fatcat create release < some_release.json + + fatcat create release --bulk < release_set.json + => makes editgroups automatically + + fatcat update container --bulk < container_set.json + => or, "fatcat update containers"? + + fatcat edit container_tupsi5ep7bhhraup4irzk6tpuy + => or "update"? + => container is fetched, $EDITOR is opened with JSON or TOML format, on + save tool validates/prettyprints (a diff?) and asks whether to make edit + +Other: + + fatcat download file_wuyi7kl4njehpg3yyngaqxcqfa + + fatcat status + => account info? + => current editgroup? + +For editgroup ergonomics, entity mutating commands (which require an +editgroup), tool should fetch recent open editgroups for the user, filter to +those created with the CLI tool, and use the most recent. Behavior and be tuned +to be more or less conservative (let's start conservative). + +At least for prototyping, configure via environment variables (eg, API token, +specifying alternative API endpoints). + +Clever but already taken names: + +- `fcc` (FatCat Client) is a fortran compiler. Also the name of the USA Federal + Communications Commission (a notable radio/internet/phone regulator) +- `fc` (FatCat) is a bash built-in. + +Argument conventions: + + ':' Lookup specifier for entity (eg, external identifier like `doi:10.123/abc`) + + '=' Assign field to value in create or update contexts. Non-string + values often can be infered by field type + + ':=' Assign field to non-string value in create or update contexts + +Small details (mostly TODO): + +- pass through API warning headers to stderr + +## Similar Tools / Interfaces + +### `httpie` + + ':' HTTP headers + + '==' URL parameters + + '=' data fields serialized into JSON, or as form data + + ':=' non-string JSON data (eg, true (boolean), 42 (number), or lists) + + '@' Form field + +Output goes to stdout (pretty-printed), unless specified to `--download / -d`), +in which case output file is infered, or `--output` sets it explicitly. + +### Internet Archive `ia` Tool + +TODO + +#### `jq` / `toml` + +Rust `toml-cli` has a small DSL for making mutations. + +#### `ripgrep` + +## More Ideas + +Some sort of pretty-printer for work/release/file structure. Eg, like `tree` +unix command. See `ptree` rust crate. + +## Implementation + +Rust libraries: + +- `toml` +- `toml_edit`: format-preserving TOML loading/mutating/serializing +- `termcolor` +- `atty` ("are we connected to a terminal") +- `tabwriter` for tabular CLI output +- `human-panic` +- `synect` for highlighting +- `exitcode` + |