A command-line tool for managing macOS Keychain items with TouchID authentication.
kctouch is a Go-based CLI tool that provides a simple and secure way to store, retrieve, and manage passwords in the macOS Keychain. All operations require TouchID authentication, ensuring that your credentials remain protected even if someone gains access to your terminal.
It can be used standalone or as a Touch ID interface for your favorite password manager CLI tool: store the master password for your database in the keychain and use kctouch to retrieve it to unlock your secrets. For example, at the time of writing, KeePassXC does not support Touch ID for its CLI. And as far as I know, there is no KeePass CLI backend that supports Touch ID authentication.
Kctouch works with generic-password keychain items only.
- π TouchID Authentication - All operations require Touch ID (with the standard macOS password fallback)
- π Keychain Integration - Seamlessly works with macOS Keychain
- π Multiple Input Methods - Support for interactive input, stdin, and command-line arguments
- π‘οΈ Secure by Default - No plaintext password storage in command history
- β‘ Fast & Lightweight - Single binary with minimal dependencies
- π― Simple Interface - Intuitive commands with helpful aliases
You probably know that the macOS security command-line tool can manage Keychain items. But granting it access to your secrets means any application with terminal access can potentially retrieve those secrets using the security command without prompting for authentication. Kctouch addresses this by adding an intermediate layer of authentication with Touch ID, enhancing security.
- macOS with TouchID support
- Go 1.24.4 or later (for building from source)
brew install rgeraskin/homebrew/kctouchgo install github.com/rgeraskin/kctouch@latestgit clone https://github.com/rgeraskin/kctouch.git
cd kctouch
go build -o kctouch
sudo mv kctouch /usr/local/bin/All commands support the following flags:
-s, --service- Service name (required for add/rm operations)-a, --account- Account name (optional)-l, --label- Label for the keychain item (optional, defaults to service name)-v, --verbose- Enable verbose logging--cache-for- Cache authentication for specified time duration (e.g. 1h, 10m, 10s)--cache-n- Cache authentication for N subsequent operations
kctouch add -s "MyService"
# You'll be prompted to enter the password securelyecho "mypassword" | kctouch add -s "MyService" -p -kctouch add -s "MyService" -p "mypassword"kctouch add -s "ghpat" -a "myuser" -l "GitHub Personal Access Token"# Update an existing password entry
kctouch add -s "MyService" -u
# Update with new password directly
kctouch add -s "MyService" -p "newpassword" --update# Get password by service name
kctouch get -s "GitHub"
# Get password by service and account
kctouch get -s "GitHub" -a "myusername"
# Get password with specific label
kctouch get -l "GitHub Personal Access Token"
# Using with scripts
API_KEY=$(kctouch get -s "myapi" -a "production")
curl -H "Authorization: Bearer $API_KEY" https://api.example.com/data
# Using in pipes
kctouch get -l keepass | keepassxc-cli show -a password -s passwords.kdbx my/password# Remove by service name
kctouch rm -s "GitHub"
# Remove by service and account
kctouch rm -s "GitHub" -a "myusername"To reduce the number of TouchID prompts during multiple operations, you can cache authentication:
# Get secret and cache authentication for 10 minutes
kctouch get -s /my/secret --cache-for 10m
# Add secret and cache authentication for 5 operations
kctouch add -s /my/secret --cache-n 5
# Remove secret and invalidate authentication cache for duration
kctouch rm -s /my/secret --cache-for 0
# Invalidate authentication cache for number of operations
kctouch noop --cache-n 0If you set both --cache-for and --cache-n in the same command, the attempts will begin to decrease from --cache-n after --cache-for expires.
Caches are only opened or extended right after a successful Touch ID prompt β see Security Considerations.
The noop command is useful for authentication caching without performing any actual keychain operations:
# Authenticate and cache for future operations
kctouch noop --cache-for 5m
# Just do nothing except auth
kctouch noopFor faster typing, kctouch supports several aliases:
- add:
a,put,set - get:
g,find - rm:
d,del,delete,remove
Examples:
kctouch a -s "service" -p "password"
kctouch g -s "service"
kctouch d -s "service"kctouch --versionUse the verbose flag to see detailed logging information:
# Enable verbose logging for any command
kctouch add -s "service" -v
kctouch get -s "service" --verbose
kctouch noop --cache-for 5m -v- Touch ID is enforced by kctouch itself, not by the Keychain. Items are stored as regular generic-password entries protected by the standard Keychain access control: other applications that try to read them trigger the system keychain prompt. The biometric gate applies to operations performed through kctouch.
- Authentication uses the system
LAPolicyDeviceOwnerAuthenticationpolicy, so the standard macOS fallbacks (device password, Apple Watch) are available in the Touch ID dialog. This keeps kctouch usable on Macs where Touch ID is temporarily unavailable (e.g. clamshell mode). - The authentication cache (
--cache-for,--cache-n) is stored as a plain keychain item without integrity protection. It is a convenience that weakens the Touch ID guarantee: a local process that can write keychain items could plant a cache entry and skip the biometric prompt. If that is part of your threat model, don't use the cache flags. - A cache window can only be opened or extended by a fresh Touch ID authentication. While a cache is live, passing
--cache-for/--cache-nagain is honored only if it shrinks the window, so a repeated command (a shell alias, a loop) cannot keep one authentication alive forever. Giving up access never requires authentication, which is what makes--cache-for 0work as an invalidation. - The service name
/kctouch/cacheis reserved for the cache item and rejected byadd. If the cache item ever becomes unreadable, kctouch ignores it and asks for Touch ID instead of failing;kctouch rm -s /kctouch/cacheclears it outright.
The toolchain is pinned with mise:
mise install # go, golangci-lint, goreleaser
mise run build # build ./kctouch with version info
mise run check # vet + lint + test + test-race (what CI runs)
mise run release-check # local goreleaser snapshot, nothing published
mise tasks # list everything elseCI runs on macOS runners because the Keychain and LocalAuthentication bindings are cgo and don't build elsewhere. Tests cover pure logic only (cache decisions, flag parsing, stdin handling), so they need neither Keychain access nor Touch ID hardware. Pushing a v* tag runs GoReleaser, which publishes the archives and updates the Homebrew formula.
- cobra - CLI framework
- go-keychain - macOS Keychain bindings
- go-touchid - TouchID authentication
This project is licensed under the MIT License - see the LICENSE file for details.
If you encounter any issues or have questions, please open an issue on GitHub.