key-cli

The command-line companion for Clavis Shell.

key-cli installs the key command and provides shell lifecycle/IPC, screen recording, audio recording and clipboard integration.

Project family

Project	Role
Clavis Shell	Quickshell UI, reactive services and native QML modules
key-cli	key command and discrete system tasks
keytop	Standalone system monitor, TUI and metrics stream

Commands

key shell
key ipc
key record
key audio
key clipboard
key doctor
key version

Shell

key shell
key shell --daemon
key shell --kill
key shell --log

IPC

key ipc show
key ipc call TARGET METHOD [ARGUMENTS...]

Screen recording

key record start --target region --type video
key record status --json
key record pause --json
key record resume --json
key record stop --json

Audio recording

key audio start --source mic --json
key audio start --source system --json
key audio status --json
key audio stop --json

Clipboard

key clipboard status --format json
key clipboard list --format json --limit 20
key clipboard inspect ID --format json
key clipboard restore ID --format json
key clipboard delete ID --format json
key clipboard clear --format json

Installation from source

Requires Python 3.10 or newer.

python -m build --wheel
sudo python -m installer dist/*.whl

The package also installs the Clavis clipboard watcher user service. Enable it with:

systemctl --user daemon-reload
systemctl --user enable --now clavis-clipboard.service

For packaged installations, prefer your distribution package manager.

External tools

Features use system executables when available:

• Quickshell (qs)
• gpu-screen-recorder
• slurp
• FFmpeg / ffprobe
• PulseAudio/PipeWire pactl
• cliphist
• wl-clipboard

Check the current environment with:

key doctor
key doctor --json

Development

python -m pip install -e '.[dev]'
ruff format .
ruff format --check .
ruff check .
python -m compileall src
python -m pytest
python -m build --wheel
scripts/check.sh

The machine-facing JSON contract is documented in docs/protocol.md. scripts/check.sh is the single local quality gate; it runs Ruff, compileall, pytest, wheel creation and a check that the packaged clipboard service is present. It does not install system files or start services.

License

See LICENSE.