Metadata-Version: 2.1
Name: arkindex-cli
Version: 0.1.1
Summary: Arkindex CLI client easy and sexy to use
Home-page: https://arkindex.teklia.com
Author: Teklia
Author-email: contact@teklia.com
License: UNKNOWN
Platform: UNKNOWN
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: arkindex-client (==1.0)
Requires-Dist: PyYAML (==5.1)
Requires-Dist: rich (==4.0.0)

# Arkindex CLI

The Arkindex CLI allows you to perform various advanced actions on an Arkindex
instance. It can both be used interactively or for scripting.

You can install this tool using pip: `pip install arkindex-cli`

To get general help about the CLI from the command line, use `arkindex -h`.
To get specific help for a subcommand, use `arkindex <subcommand> -h`.

## Logging in

To interact with an Arkindex instance, you first need to log in with your
email and password. To do so, use this command:

```
arkindex login
```

You will be asked for the instance URL, your email and your password.
If it all goes well, you will be asked for an alias under which the
credentials should be stored, and whether or not these should be the default
credentials to use for all other commands.

The credentials are then stored in a YAML file at
`~/.config/arkindex/cli.yaml`. Your email and password are not directly stored;
only the instance URL and an API token.

In any subcommand, you can use the `-p` or `--profile` arguments to select a
profile other than your default. For example, if you are logged in to two
instances using the aliases `Foo` and `Bar`, and your default instance is
`Foo`, all `arkindex` commands will login to `Foo` by default, and you can
connect to `Bar` using `arkindex --profile Bar <subcommand>`.

## ML reports

Arkindex machine learning workers can return `ml_report.json` artifacts; JSON
files that describe which elements a worker processed, along with the created
elements, classifications or transcriptions and the encountered errors.

The CLI can fetch all of the ML reports for a DataImport and provide statistics
on the errors:

```
arkindex import report <DataImport ID>
```

A possible output might be:

```
11061 elements: 10575 successful, 486 with errors
    Errors by class
┏━━━━━━━━━━━━━┳━━━━━━━┓
┃ Class       ┃ Count ┃
┡━━━━━━━━━━━━━╇━━━━━━━┩
│ HTTPError   │   470 │
│ KeyError    │    15 │
│ ReadTimeout │     1 │
└─────────────┴───────┘
```

By default, this command retrieves the ML reports for the latest run of the
DataImport. If you want to use another run, you can specify its number using
`-r` or `--run`:

```
arkindex import report <DataImport ID> --run 4
```

### Output modes

A JSON mode is available with the `-j` or `--json` arguments.
This will return an object with all elements from all ML reports that have
at least one error.

You can also display the full error messages and tracebacks with syntax
highlighting using `-v` or `--verbose`.

## Import recovery

It is possible to start a new DataImport on another DataImport's failed
elements (elements with at least one error):

```
arkindex import recover <DataImport ID>
```

This will retrieve the ML reports, list the failed elements, then add them to
your selection. A link will be provided to then open the Arkindex frontend,
allowing you to configure and start your new import.

Since this updates your selection, if you already had selected elements, the
tool will ask for your confirmation before deselecting them.

By default, this command retrieves failed elements from the ML reports for the
latest run of the DataImport. If you want to use another run, you can specify
its number using `-r` or `--run`:

```
arkindex import recover <DataImport ID> --run 4
```


