From 5bef711fadabac1844cf4d5820ccf85b2fa465ae Mon Sep 17 00:00:00 2001 From: Jack Rosenthal Date: Fri, 16 Feb 2024 01:19:26 -0700 Subject: [PATCH] cli: Move the documentation to markdown --- algobowl/templates/cli_setup.xhtml | 65 +++----------------------- docs/cli.md | 74 ++++++++++++++++++++++++++++++ docs/problem_format.md | 5 +- 3 files changed, 84 insertions(+), 60 deletions(-) create mode 100644 docs/cli.md diff --git a/algobowl/templates/cli_setup.xhtml b/algobowl/templates/cli_setup.xhtml index 34d564a..042cdee 100644 --- a/algobowl/templates/cli_setup.xhtml +++ b/algobowl/templates/cli_setup.xhtml @@ -14,66 +14,13 @@ in the CLI.

-

Installation

+ + Documentation + -

- Download the - launcher script - and mark it executable. For example: -

- -

- curl https://raw.githubusercontent.com/jackrosenthal/algobowl/main/cli_launcher.py -o algobowl && chmod +x algobowl -

- -

- You can either put it in a location referenced by your PATH - environment variable and run it as algobowl, or it's designed - so you can check it in to your group's Git repo as well (and run it as - ./algobowl). -

- -

- The launcher is designed to depend on nothing but Python 3.8+, so you - don't need to worry about installing any dependencies. -

- -

Authentication

- -

- Run algobowl auth login and follow the instructions. -

- -

Usage

- -

- Run algobowl --help for help. Here are some commands you may - be interested in: -

- -

Input Upload

- - - -

Output Upload

- - - -

- Note: if you use filenames containing the group ID, (e.g., - output_group123.txt), the CLI can infer the group ID from the - filename, and passing --to-group-id is not required. -

- -

Logged-in Clients

+

Logged-in Clients

Your currently logged-in clients are listed below. diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..a3170cf --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,74 @@ +# AlgoBOWL CLI + +The AlgoBOWL CLI provides convenient access to interact with AlgoBOWL from your +command line and from scripts. + +**The CLI is still very much in beta state, and not complete yet.** +Improvements are welcome (send patches!) + +## System Requirements + +The only requirement is Python 3.8 or newer. The CLI is best-supported on +Linux, however, it may work on Windows and Mac as well. Patches are welcome +if it doesn't work on Windows or Mac. + +## Installation + +Download [`cli_launcher.py`](../cli_launcher.py) and mark it executable. It's +recommended to name this file `algobowl` and put it somewhere on your `PATH`. +Alternatively, you could download it into your group's Git repository and use it +as `./algobowl` from there. + +``` shellsession +$ curl https://raw.githubusercontent.com/jackrosenthal/algobowl/main/cli_launcher.py -o algobowl && chmod +x algobowl +``` + +The CLI launcher will download the CLI and dependencies, and keep them up to +date as required. If you prefer to manage your own installation, or plan on +hacking on the CLI source code, you can install an "editable copy" of this +repository using `pip` instead: + +``` shellsession +$ pip install -e . +``` + +## Usage + +Detailed usage can be found by running `algobowl --help`. + +### Authenticating to an AlgoBOWL server + +Run `algobowl auth login` and follow the instructions. You can then verify +you've successfully logged in by running `algobowl auth whoami`. + +The default server is `https://mines.algobowl.org`. You can choose another +server by running `algobowl config set-default-server ...`. + +### Group Commands + +You can perform actions on behalf of your group using `algobowl group` commands. +By default, if you're only a member of one active group, it'll be selected for +group commands. If you're a member of multiple groups, or you're a site +administrator and want to act on behalf of another group, you can pass +`--group-id` to specify your group ID. Here are some commands which may be of +interest: + +#### Input Upload + +* `algobowl group input upload FILENAME`: Upload your group's input. +* `algobowl group input download OUTPUT_FILE`: Download your group's input. +* `algobowl group set-team-name TEAM_NAME`: Set your team name. + +#### Output Upload + +* `algobowl group output --to-group-id GROUP_ID upload FILENAME`: Upload an + output. +* `algobowl group output --to-group-id GROUP_ID download OUTPUT_FILE`: Download + one of your submitted outputs. +* `algobowl group output list`: List output files you'll need to provide. + +Note: if you use filenames containing the group ID, (e.g., +`output_group123.txt`), the CLI can infer the group ID from the filename, and +passing `--to-group-id` is not required. When multiple IDs appear in the +filename (e.g., `output_from_group120_to_group123.txt`), the second ID +is used. diff --git a/docs/problem_format.md b/docs/problem_format.md index 370c0ab..ac73e6a 100644 --- a/docs/problem_format.md +++ b/docs/problem_format.md @@ -32,7 +32,10 @@ required to implement on their own. Validate you have access (requesting it from Jack if necessary). This is where you are going to push your problem implementation. -## Setup AlgoBOWL development environment +## Set up the AlgoBOWL CLI + +The AlgoBOWL CLI is used to run the problem tester. Set it up by following +[these instructions](./cli.md). Clone this repository, and create a new Python virtual environment: