From 0f89be721b820fe295cacfd5e3c875d3037b9874 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Tue, 9 Feb 2021 20:01:05 -0800 Subject: start re-writing README --- README.md | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 95 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index a5c1f49..48eb200 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,100 @@ -**fatcat-cli**: command-line utility for interacting with https://fatcat.wiki API +
+ + + +
+`fatcat-cli`: api.fatcat.wiki command-line utility +==================================================== -## History / Status +**DISCLAIMER:** this tool is still under development. The interface (arguments, +flags) and default behaviors are not yet stable. -This side-project is currently a work-in-progress. +## Install -Eventually intend to merge this repo back in to the main fatcat git repo, but -it currently uses a newer version of the openapi code generator tool. Updating -the fatcat API server rust code (`fatcatd`) will take a good deal of -refactoring, and this version of the codegen tool isn't even stable at the time -this fork started. +Debian/Ubuntu Linux users can install bare `.deb` packages. Download the most +recent from , then install with: + + sudo apt install ./fatcat-cli-*.deb + + + + + +## Quickstart + +Query the catalog: + + fatcat search releases "metadata author:phillips" + +Fetch metadata for a specific work: + + fatcat get doi:10.1002/spe.659 + +Download 100 papers from a specific journal, as PDF: + + fatcat search releases journal:"first monday" --entity-json --expand files | fatcat batch download --limit 100 + +### Authentication + +To propose changes to the catalog, you need a account. +You can create one quickly by logging in with an existing Internet Archive, +ORCiD, Wikipedia, or Gitlab account. Create a new API token from the [account +page](https://fatcat.wiki/auth/account), and set this token (a long sequence of +characters) as an environment variable in your shell: + + export FATCAT_API_AUTH_TOKEN=... + +You could put this in a secrets/password manager so you don't lose it. Or, +depending on your setup, in a`~/.profile`. The tool does not (yet) +automatically load "dotenv" (`./.env`) files, but you might be using a +project-management tool which does so already. + +You can check the status of your authentication and connection to the server +with: + + fatcat status + +### Editing + +Every change to the catalog (an "edit") is made as part of an "editgroup". In +some cases the CLI tool with create or guess what the current editgroup you are +working on is, but you can also create them explicitly and pass the editgroup +identifier on every subsequent edit. It is best to combine small groups of +related changes into the same editgroup (so they can be reviewed together), but +to split up larger batches into editgroups of 50-100 changes at a time. + +Individual entities can be edited from the convenience of your text editor, in +either JSON or TOML format: + + fatcat get release_hsmo6p4smrganpb3fndaj2lon4 --json > release_hsmo6p4smrganpb3fndaj2lon4.json + + # whatever editor you prefer + emacs release_hsmo6p4smrganpb3fndaj2lon4 + + fatcat update release_hsmo6p4smrganpb3fndaj2lon4 < release_hsmo6p4smrganpb3fndaj2lon4. +json + +Or, with a single command: + + fatcat edit release_hsmo6p4smrganpb3fndaj2lon4 --toml + +To check in on the status of recent editgroups, or to "submit" them for review: + + fatcat editgroups list + fatcat editgroups submit editgroup_... + +## Thanks! + +The "keyboard cat" photo at the top of this README is by Cassandra Leigh Gotto ([threecheersformcr_xo](https://www.flickr.com/photos/threecheersformcr_xo/5340309206/)) and shared under the [CC-BY-NC](https://creativecommons.org/licenses/by-nc/2.0/) license. -- cgit v1.2.3