diff options
| -rw-r--r-- | README.md | 103 |
1 files changed, 95 insertions, 8 deletions
@@ -1,13 +1,100 @@ -**fatcat-cli**: command-line utility for interacting with https://fatcat.wiki API +<div align="center"> +<!-- https://www.flickr.com/photos/threecheersformcr_xo/5340309206/ --> +<!-- TODO: move to an archive.org item... or just include in this repo --> +<img src="http://static.bnewbold.net/tmp/keyboard-cat-flickr-threecheersformcr_xo.jpg"> +</div> +`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 <http://archive.org/download/ia-fatcat-cli-bin>, then install with: + + sudo apt install ./fatcat-cli-*.deb + +<!-- +MacOS Homebrew users with Intel CPUs, can install using a "tap": + + brew install bnewbold/fatcat/fatcat-cli +--> + +<!-- +Users on all other platforms can use the Rust `cargo` tool to build and install +the utility for their user. Unfortunately this will not include the manual +("man page") or shell completions: + + cargo install fatcat-cli +--> + +## 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 <https://fatcat.wiki> 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. |