canokey-manager 5.9.2.post1

== CanoKey Manager CLI
image:https://github.com/canokeys/canokey-manager/actions/workflows/source-package.yml/badge.svg["Source package build", link="https://github.com/canokeys/canokey-manager/actions/workflows/source-package.yml"]
image:https://github.com/canokeys/canokey-manager/actions/workflows/windows.yml/badge.svg["Windows build", link="https://github.com/canokeys/canokey-manager/actions/workflows/windows.yml"]
image:https://github.com/canokeys/canokey-manager/actions/workflows/macOS.yml/badge.svg["MacOS build", link="https://github.com/canokeys/canokey-manager/actions/workflows/macOS.yml"]
image:https://github.com/canokeys/canokey-manager/actions/workflows/ubuntu.yml/badge.svg["Ubuntu build", link="https://github.com/canokeys/canokey-manager/actions/workflows/ubuntu.yml"]

Python 3.10 (or later) library and command line tool for configuring a CanoKey.
This project is a fork of https://github.com/Yubico/yubikey-manager[YubiKey Manager].
Install the `canokey-manager` package and use the `ckman` command.
The Python import namespaces remain `ykman` and `yubikit`.

=== Usage
For upstream usage information and examples, see the https://docs.yubico.com/software/yubikey/tools/ykman/Using_the_ykman_CLI.html[YubiKey Manager CLI User Manual].
Use `ckman` in place of `ykman`; command availability depends on CanoKey firmware.
See the link:doc/CanoKey-Firmware-Versions.md[firmware protocol changelog].

The following lists commands applicable to CanoKey. The inherited `config`
command cannot configure CanoKey applications. Yubico OTP (`otp`), YubiHSM
Auth (`hsmauth`), and Security Domain (`securitydomain`) are not supported on
CanoKey, even if their command entries appear in the CLI help.

....
Usage: ckman [OPTIONS] COMMAND [ARGS]...

  Configure your CanoKey via the command line.

  Examples:

    List connected CanoKeys, only output serial number:
    $ ckman list --serials

    Show information about CanoKey with serial number 0123456:
    $ ckman --device 0123456 info

Options:
  -d, --device SERIAL             specify which CanoKey to interact with by serial number
  -r, --reader NAME               specify a CanoKey by smart card reader name (can't be used with --device or list)
  -l, --log-level [ERROR|WARNING|INFO|DEBUG|TRAFFIC]
                                  enable logging at given verbosity level
  --log-file FILE                 write log to FILE instead of printing to stderr (requires --log-level)
  --diagnose                      show diagnostics information useful for troubleshooting
  -v, --version                   show version information about the app
  --full-help                     show --help output, including hidden commands
  -h, --help                      show this message and exit

Commands for CanoKey:
  info     show general information
  list     list connected CanoKeys
  fido     manage the FIDO applications
  oath     manage the OATH application
  openpgp  manage the OpenPGP application
  piv      manage the PIV application
....

The `--help` argument can also be used to get detailed information about specific
subcommands:

    ckman oath --help

=== Versioning/Compatibility
This project follows https://semver.org/[Semantic Versioning]. Any project
depending on canokey-manager should take care when specifying version ranges to
not include any untested major version, as it is likely to have backwards
incompatible changes. For example, you should NOT depend on ">=5", as it has no
upper bound. Instead, depend on ">=5, <6", as any release before 6 will be
compatible.

Note that any private variables (names starting with '_') are not part of the
public API, and may be changed between versions at any time.

=== Installation
CanoKey Manager can be installed independently of platform by using pip (or
equivalent):

  pip install --user canokey-manager

On Linux platforms you will need `pcscd` installed and running to be able to
communicate with a CanoKey over the SmartCard interface. Additionally, you may
need to set permissions for your user to access CanoKey via the FIDO HID interface.
See the Smart Card Access and FIDO Access sections in
link:doc/Device_Permissions.adoc[Device Permissions].

Some of the libraries used by canokey-manager have C-extensions, and may require
additional dependencies to build, such as http://www.swig.org/[swig] and
potentially https://pcsclite.apdu.fr/[PCSC lite].

=== Pre-built packages
Use the `canokey-manager` Python package for this fork. Packages named
`yubikey-manager` from Yubico or third parties install the upstream project.

==== Windows
The CanoKey fork does not publish a standalone Windows installer. Install the
`canokey-manager` Python package instead; Windows remains covered by CI tests.

==== MacOS
Install the Python package above. The
https://github.com/canokeys/canokey-manager/actions/workflows/macOS.yml[macOS workflow]
also builds a `ckman.pkg` installer in the `ckman-builds-macos` artifact.

===== Uninstallation of the MacOS .pkg
To uninstall CanoKey Manager when installed via the .pkg installer, run:

  $ sudo rm -rf /usr/local/bin/ckman /usr/local/ckman

==== Linux
Python-specific tools such as pip, pipx, or uv can be used directly to install and
manage canokey-manager, and are the recommended approach.

==== FreeBSD
CanoKey Manager is not covered by this project's CI on FreeBSD. The
`pyXY-yubikey-manager` port installs upstream YubiKey Manager, not this fork.

==== From source (for development)
To install and run this fork from source:

  $ git clone https://github.com/canokeys/canokey-manager.git
  $ cd canokey-manager
  $ uv sync --locked
  $ uv run ckman --help

See the link:doc/Development.adoc[development] instructions for dependencies
and tooling; use the repository above and `ckman` in place of `ykman`.

=== Shell completion

Experimental shell completion for the command line tool is available, provided
by the underlying CLI library (`click`) but it is not enabled by default. To
enable it, run this command once (for Bash):

  $ source <(_CKMAN_COMPLETE=bash_source ckman | sudo tee /etc/bash_completion.d/ckman)

More information on shell completion (including instructions for other shells) is
available at:
https://click.palletsprojects.com/en/stable/shell-completion/