summaryrefslogtreecommitdiffstats
path: root/proposals/2020_client_cli.md
blob: 2a0c8fa1672c6dd4618652fbcbc8aca793ba839b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
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`