# Internal API
Source: https://cihai-cli.git-pull.com/api/

(api)=

```{module} cihai_cli

```

# Internal API

```{seealso}

{ref}`cihai's API <cihai:api>`

```

## Internals

```{warning}
These APIs are purely internal not covered by versioning policies, they can and will
break between versions. If you need an internal API stabilized please
[file an issue](https://github.com/cihai/cihai-cli/issues).
```

```{eval-rst}
.. automodule:: cihai_cli.cli
   :members:
   :undoc-members:
   :special-members:
   :show-inheritance:
```

---

# Completions
Source: https://cihai-cli.git-pull.com/cli/completion/

(completion)=

(completions)=

(cli-completions)=

# Completions

## cihai-cli 0.15+ (experimental)

```{note}
See the [shtab library's documentation on shell completion](https://docs.iterative.ai/shtab/use/#cli-usage) for the most up to date way of connecting completion for cihai-cli.
```

Provisional support for completions in cihai-cli 0.15+ are powered by [shtab](https://docs.iterative.ai/shtab/). This must be **installed separately**, as it's **not currently bundled with cihai-cli**.

```console
$ pip install shtab --user
```

Or manage it inside an existing project with uv:

```console
$ uv add --dev shtab
```

Install `shtab` as a user-wide tool with uv:

```console
$ uv tool install shtab
```

Run it on-demand without installing:

```console
$ uvx shtab
```

:::{tab} bash

```console
$ shtab --shell=bash -u cihai_cli.cli.create_parser \
  | sudo tee "$BASH_COMPLETION_COMPAT_DIR"/CIHAI
```

:::

:::{tab} zsh

```console
$ shtab --shell=zsh -u cihai_cli.cli.create_parser \
  | sudo tee /usr/local/share/zsh/site-functions/_CIHAI
```

:::

:::{tab} tcsh

```console
$ shtab --shell=tcsh -u cihai_cli.cli.create_parser \
  | sudo tee /etc/profile.d/CIHAI.completion.csh
```

:::

## cihai-cli 0.2 to 0.14

```{note}
See the [click library's documentation on shell completion](https://click.palletsprojects.com/en/8.0.x/shell-completion/) for the most up to date way of connecting completion for cihai.
```

cihai-cli 0.2 to 0.14 use [click](https://click.palletsprojects.com)'s completion:

:::{tab} bash

_~/.bashrc_:

```bash

eval "$(_CIHAI_COMPLETE=bash_source cihai)"

```

:::

:::{tab} zsh

_~/.zshrc_:

```zsh

eval "$(_CIHAI_COMPLETE=zsh_source cihai)"

```

:::

---

# CLI Reference
Source: https://cihai-cli.git-pull.com/cli/

(cli)=

# CLI Reference

::::{grid} 1 1 2 2
:gutter: 2 2 3 3

:::{grid-item-card} cihai info
:link: info
:link-type: doc
Look up a CJK character by glyph or codepoint.
:::

:::{grid-item-card} cihai reverse
:link: reverse
:link-type: doc
Search definitions for a given term.
:::

:::{grid-item-card} Completions
:link: completion
:link-type: doc
Shell completion for bash, zsh, and tcsh.
:::

::::

```{toctree}
:caption: General
:maxdepth: 1

info
reverse
```

```{toctree}
:caption: Completion
:maxdepth: 1

completion
```

(cli-main)=

(cihai-main)=

(cihai-cli-main)=

## Command: `cihai`

```{eval-rst}
.. argparse::
    :module: cihai_cli.cli
    :func: create_parser
    :prog: cihai
    :nosubcommands:

    subparser_name : @replace
        See :ref:`cli-info`, :ref:`cli-reverse`
```

---

# cihai info
Source: https://cihai-cli.git-pull.com/cli/info/

(cli-info)=

(cihai-info)=

# cihai info

## Command

```{eval-rst}
.. argparse::
    :module: cihai_cli.cli
    :func: create_parser
    :prog: cihai
    :path: info
```

---

# cihai reverse
Source: https://cihai-cli.git-pull.com/cli/reverse/

(cli-reverse)=

(cihai-reverse)=

# cihai reverse

## Command

```{eval-rst}
.. argparse::
    :module: cihai_cli.cli
    :func: create_parser
    :prog: cihai
    :path: reverse
```

---

# Changelog
Source: https://cihai-cli.git-pull.com/history/

(history)=

```{include} ../CHANGES

```

---

# cihai-cli
Source: https://cihai-cli.git-pull.com/

(index)=

# cihai-cli

Command line frontend for the [cihai](https://cihai.git-pull.com/) CJK language library.

::::{grid} 1 2 3 3
:gutter: 2 2 3 3

:::{grid-item-card} Quickstart
:link: quickstart
:link-type: doc
Install and look up your first character.
:::

:::{grid-item-card} CLI Reference
:link: cli/index
:link-type: doc
Every command, flag, and option.
:::

:::{grid-item-card} Contributing
:link: project/index
:link-type: doc
Development setup, code style, and releases.
:::

::::

## Install

```console
$ pip install cihai-cli
```

```console
$ uv tool install cihai-cli
```

## At a glance

Look up a CJK character:

```console
$ cihai info 好
```

```
char: 好
kDefinition: good, excellent, fine; well
kMandarin: hǎo
```

Search definitions:

```console
$ cihai reverse library
```

```
圕: library
```

Data is downloaded automatically on first use via [cihai](https://cihai.git-pull.com/).

```{toctree}
:hidden:

quickstart
cli/index
api
project/index
history
migration
GitHub <https://github.com/cihai/cihai-cli>
```

---

# Migration notes
Source: https://cihai-cli.git-pull.com/migration/

(migration)=

```{include} ../MIGRATION

```

---

# Code Style
Source: https://cihai-cli.git-pull.com/project/code-style/

# Code Style

## Formatting

cihai-cli uses [ruff](https://github.com/astral-sh/ruff) for both linting and formatting.

```console
$ uv run ruff format .
```

```console
$ uv run ruff check . --fix --show-fixes
```

## Type Checking

Strict [mypy](https://mypy-lang.org/) is enforced.

```console
$ uv run mypy
```

## Docstrings

All public functions and methods use NumPy-style docstrings.

## Imports

- Standard library: namespace imports (`import pathlib`, not `from pathlib import Path`)
- Typing: `import typing as t`, access via `t.Optional`, `t.NamedTuple`, etc.
- All files: `from __future__ import annotations`

---

# Contributing
Source: https://cihai-cli.git-pull.com/project/contributing/

# Contributing

cihai-cli follows the cihai project's contributing guidelines.

See the [cihai contributing guide](https://cihai.git-pull.com/contributing/) for
development setup, running tests, and submitting pull requests.

## Quick setup

Clone and install in development mode:

```console
$ git clone https://github.com/cihai/cihai-cli.git
```

```console
$ cd cihai-cli
```

```console
$ uv sync --group dev
```

Run the tests:

```console
$ uv run pytest
```

---

# Project
Source: https://cihai-cli.git-pull.com/project/

(project)=

# Project

Information for contributors and maintainers.

::::{grid} 1 1 2 2
:gutter: 2 2 3 3

:::{grid-item-card} Contributing
:link: contributing
:link-type: doc
How to get involved and submit changes.
:::

:::{grid-item-card} Code Style
:link: code-style
:link-type: doc
Ruff, mypy, NumPy docstrings, import conventions.
:::

:::{grid-item-card} Releasing
:link: releasing
:link-type: doc
Release checklist and version policy.
:::

::::

```{toctree}
:hidden:

contributing
code-style
releasing
```

---

# Releasing
Source: https://cihai-cli.git-pull.com/project/releasing/

# Releasing

## Release Process

Releases are triggered by git tags and published to PyPI via OIDC trusted publishing.

1. Update `CHANGES` with the release notes

2. Bump version in `src/cihai_cli/__about__.py`

3. Commit:

   ```console
   $ git commit -m "cihai-cli <version>"
   ```

4. Tag:

   ```console
   $ git tag v<version>
   ```

5. Push:

   ```console
   $ git push && git push --tags
   ```

6. CI builds and publishes to PyPI automatically via trusted publishing

---

# Usage
Source: https://cihai-cli.git-pull.com/quickstart/

(usage)=

# Usage

cihai is designed to work out-of-the-box without configuration.

## Installation

```console
$ pip install --user cihai-cli
```

Or manage it inside an existing project with uv:

```console
$ uv add cihai-cli
```

Install the CLI as a user-wide tool with uv:

```console
$ uv tool install cihai-cli
```

Run it on-demand without installing:

```console
$ uvx --from cihai-cli cihai --version
```

### Developmental releases

New versions of cihai CLI are published to PyPI as alpha, beta, or release candidates. In their
versions you will see notification like `a1`, `b1`, and `rc1`, respectively. `1.10.0b4` would mean
the 4th beta release of `1.10.0` before general availability.

- [pip]\:

  ```console
  $ pip install --user --upgrade --pre cihai-cli
  ```

- [pipx]\:

  ```console
  $ pipx install --suffix=@next 'cihai-cli' --pip-args '\--pre' --force
  // Usage: cihai@next info 好
  ```

- [uv tool install][uv-tools]\:

  ```console
  $ uv tool install --prerelease=allow cihai-cli
  ```

- [uv]\:

  ```console
  $ uv add cihai-cli --prerelease allow
  ```

- [uvx]\:

  ```console
  $ uvx --from 'cihai-cli' --prerelease allow cihai
  ```

via trunk (can break easily):

- [pip]\:

  ```console
  $ pip install --user -e git+https://github.com/cihai/cihai-cli.git#egg=cihai-cli
  ```

- [uv]\:

  ```console
  $ uv add git+https://github.com/cihai/cihai-cli.git#egg=cihai-cli
  ```

- [pipx]\:

  ```console
  $ pipx install --suffix=@master 'cihai-cli @ git+https://github.com/cihai/cihai.git@master' --include-deps --force
  ```

[pip]: https://pip.pypa.io/en/stable/
[pipx]: https://pypa.github.io/pipx/docs/
[uv]: https://docs.astral.sh/uv/
[uv-tools]: https://docs.astral.sh/uv/concepts/tools/
[uvx]: https://docs.astral.sh/uv/guides/tools/

## Configuration

See {ref}`cihai's configuration <cihai:configuration>` documentation.

---