@keyboard-hub/abyss-cli

Command line client for Keyboard Abyss. Use it from a terminal, scripts, or AI agent workflows to authenticate with Abyss, read/write keymaps through the OAuth API, and exchange keymaps with locally connected keyboards.

The CLI wraps @keyboard-hub/abyss-client for OAuth and API access, and routes connected-keyboard work through the firmware adapter packages when the current runtime exposes the required device APIs.

For repository-local development, see DEVELOPMENT.md.

Quick Start

npx @keyboard-hub/abyss-cli --help
npx @keyboard-hub/abyss-cli auth login
npx @keyboard-hub/abyss-cli keymaps list --json

auth login uses the official public Keyboard Abyss CLI OAuth client by default. It opens the browser, waits for Abyss to redirect back to a temporary localhost callback server, exchanges the authorization code, and stores the resulting token locally.

For custom Abyss deployments or development OAuth clients, pass --client-id or set ABYSS_CLIENT_ID. The loopback login command expects this redirect URI unless you pass a custom --redirect-uri registered on that client:

http://127.0.0.1:39817/oauth/callback

After the first login, the CLI stores the token locally and refreshes it through @keyboard-hub/abyss-client before API calls.

Auth

abyss auth login
abyss auth begin --json
abyss auth complete --callback-url 'http://127.0.0.1:39817/oauth/callback?code=...&state=...'
abyss auth status
abyss auth refresh
abyss auth logout

auth login starts a temporary localhost callback server and opens the browser. auth begin and auth complete split the same PKCE flow into automation-safe steps.

Tokens are stored under ~/.keyboard-abyss by default. Use --storage keychain or ABYSS_CLI_STORAGE=keychain on macOS to store tokens in Keychain. --storage auto uses Keychain when available and falls back to the dotfile.

Useful environment variables:

• ABYSS_CLIENT_ID: override the official CLI OAuth client ID.
• ABYSS_BASE_URL: target Abyss origin, for example a dev deployment.
• ABYSS_REDIRECT_URI: OAuth callback URI.
• ABYSS_CONFIG_DIR: config/token directory instead of ~/.keyboard-abyss.
• ABYSS_CLI_STORAGE: file, keychain, or auto.

Keymaps

abyss keymaps list --visibility all --json
abyss keymaps get KEYMAP_ID --output keymap.json
abyss keymaps export KEYMAP_ID --format zmk --output daily.keymap
abyss keymaps import keyboardhub.json --name daily --private

Import accepts either a KeyboardHub keymap JSON document or a KeyboardHub keyboard export containing { "layout": ..., "keymap": ... }.

Use --stdout when composing commands without temporary files:

abyss keymaps export KEYMAP_ID --format keyboardhub --stdout --json

Connected Keyboards

abyss device methods --json
abyss device devices --method zmk --json
abyss device import --method zmk --transport usb --output connected.json
abyss device import --method zmk --transport usb --save-to-abyss
abyss device export --method zmk --transport usb --keymap-id KEYMAP_ID --write
abyss device export --method via --transport usb --input keymap.json --dry-run

device import reads from a connected keyboard. device export writes a local or Abyss keymap to a connected keyboard. ZMK USB commands can use the CLI's local serial-port shim in Node.js on Unix-like systems; ZMK WebUSB and BLE still require browser-style navigator.usb or navigator.bluetooth. VIA and Vial USB commands can use browser navigator.hid or the optional node-hid dependency in Node.js. Use --device-name, --device, --device-path, --vendor-id, or --product-id when more than one matching device is connected. When no supported local device API is available, device commands return an unsupported_transport error in JSON mode instead of opening an interactive picker.

VIA direct reads need layout metadata for physical key order and matrix positions. Pass a VIA keyboard definition, a KeyboardHub layout JSON, or a KeyboardHub keyboard export with { "layout": ... }:

abyss device import --method via --device-name abyss-tester \
  --definition via.json --output connected.json --json
abyss device export --method via --device-name abyss-tester \
  --input connected.json --definition via.json --write --json

The adapter packages are optional peers so API-only commands can run from npx. Install or run the CLI inside a workspace that provides the matching adapter package before using device commands:

npx @keyboard-hub/abyss-cli device import --method zmk --transport usb --json

Repository-local real-device smoke coverage for the VIA/Vial wrappers lives in scripts/test-abyss-cli-via-vial-devices.mjs. ZMK Studio coverage lives in scripts/test-abyss-cli-zmk-device.mjs and currently exercises the local import/export plumbing plus devtool lock/unlock around a no-op writeback. These scripts do not talk to the Abyss API.

Non-Interactive Mode

Pass --json for machine-readable output and stable error objects:

{
  "ok": false,
  "error": {
    "code": "unknown_command",
    "message": "Unknown command: ..."
  }
}

Exit codes:

• 0: success
• 1: runtime error
• 2: usage or validation error
• 64: unsupported local device transport
• 65: authentication or authorization error

For fully non-interactive OAuth, use auth begin --json, open the returned authorization URL in a browser under user control, then pass the final callback URL to auth complete --json. This avoids prompts and keeps stdout parseable.