summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBryan Newbold <bnewbold@robocracy.org>2020-06-30 11:18:08 -0700
committerBryan Newbold <bnewbold@robocracy.org>2020-06-30 11:18:08 -0700
commitca8fa64c1590a43b1e92fd8898275625d083451a (patch)
tree2a7ff1d2edc89e09a9c6cf0f25dcc55e451bfac9
parent1ac95b3691bf4168ace4d5f50690e4b1e6b74871 (diff)
downloadfatcat-ca8fa64c1590a43b1e92fd8898275625d083451a.tar.gz
fatcat-ca8fa64c1590a43b1e92fd8898275625d083451a.zip
CLI proposal
-rw-r--r--proposals/2020_client_cli.md124
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`
+