# Command-Line Usage

The primary CLI for sphobjinv is implemented using two subcommands of the `sphobjinv` entrypoint:

> - `sphobjinv convert` (docs page), which handles conversion of inventories between supported formats (currently zlib-compressed, plaintext, and JSON).

> - `sphobjinv suggest` (docs page), which provides suggestions for objects in an inventory matching a desired search term.

As of v2.4, sphobjinv also provides an auxiliary entrypoint, `sphobjinv-textconv` (docs page), which takes one required argument: a path to a file on disk. This entrypoint attempts to instantiate an `Inventory` with this file and emit its plaintext contents to stdout with no cosmetic whitespace. The following two invocations are thus nearly synonymous:

    $ sphobjinv convert plain path/to/objects.inv -

    $ sphobjinv-textconv path/to/objects.inv

(Be sure to note the final hyphen in the first command.) The `sphobjinv-textconv` spelling is less awkward when configuring a Git textconv to allow rendering diffs of objects.inv files in plaintext. See the `sphobjinv-textconv` entrypoint documentation for more information.

Shell examples in the CLI docs execute from within /tests/resource unless indicated otherwise.

For Python examples:

> - Examples are executed in a sandboxed directory pre-loaded with objects_attrs.inv (from, e.g., here).

> - `Path` (from `pathlib`) is imported into the namespace before all tests.

> - cli_run is a helper function that enables doctesting of CLI examples by mimicking execution of a shell command. It is described in more detail here.

> - file_head is a helper function that retrieves the head of a specified file.