# EasyKey Python Package
A simple Python wrapper for the [easykey](https://github.com/kingofmac/easykey) CLI that provides secure keychain access on macOS.
## Installation
### Prerequisites
1. First, ensure you have the `easykey` CLI installed and available in your PATH
2. Install this Python package:
```bash
pip install easykey
```
### Local Development Installation
If you're working with the source code:
```bash
cd python
pip install -e .
```
## Usage
### Basic Secret Retrieval
```python
import easykey
# Get a secret (this will trigger biometric authentication)
secret = easykey.secret("MySecretName")
print(secret)
# Get a secret with a reason for audit logging
secret = easykey.secret("MySecretName", "Connecting to production database")
```
### Listing and Status
```python
import easykey
# List all secret names
secrets = easykey.list()
for secret in secrets:
print(f"Secret: {secret['name']}")
# List secrets with creation timestamps
secrets = easykey.list(include_timestamps=True)
for secret in secrets:
print(f"Secret: {secret['name']}, Created: {secret.get('createdAt', 'Unknown')}")
# Get vault status
status = easykey.status()
print(f"Total secrets: {status['secrets']}")
print(f"Last access: {status['last_access']}")
```
## API Reference
### Functions
- **`secret(name, reason=None)`** - Retrieve a secret value
- **`get_secret(name, reason=None)`** - Alias for `secret()`
- **`list(include_timestamps=False)`** - List all secrets
- **`status()`** - Get vault status information
### Parameters
- **`name`** (str): The name/identifier of the secret
- **`reason`** (str, optional): Reason for the operation (for audit logging)
- **`include_timestamps`** (bool): Whether to include creation timestamps in list results
### Return Values
- **`secret()`** returns the secret value as a string
- **`list()`** returns a list of dictionaries with secret information
- **`status()`** returns a dictionary with vault status
### Exceptions
All functions may raise **`EasyKeyError`** if the underlying CLI operation fails.
## Security Notes
- This package is a thin wrapper around the easykey CLI
- All security features (biometric authentication, keychain integration) are handled by the CLI
- Secrets are retrieved through subprocess calls and are not cached in Python
- The package automatically locates the easykey binary in common installation paths
## Requirements
- macOS (required by the underlying easykey CLI)
- Python 3.7+
- easykey CLI installed and accessible
## Quick Start Example
```python
import easykey
# Check vault status
status = easykey.status()
print(f"Vault contains {status['secrets']} secrets")
# List all secrets
secrets = easykey.list()
for secret in secrets:
print(f"Found secret: {secret['name']}")
# Retrieve a specific secret (requires biometric authentication)
secret_value = easykey.secret("MySecretName", "Accessing for API call")
print(f"Secret value: {secret_value}")
```
**Note:** This is a **read-only** package. To store or manage secrets, use the easykey CLI directly.
## License
MIT License - see the main easykey project for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/kingofmac/easykey",
"name": "easykey",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "keychain, security, secrets, macOS, CLI, wrapper",
"author": "KingOfMac",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/70/ff/5e3a719a38ce60fbee072ca9ed585dbc324ffd07d0fd2ebdc5be5f1e1485/easykey-0.1.0.tar.gz",
"platform": null,
"description": "# EasyKey Python Package\n\nA simple Python wrapper for the [easykey](https://github.com/kingofmac/easykey) CLI that provides secure keychain access on macOS.\n\n## Installation\n\n### Prerequisites\n\n1. First, ensure you have the `easykey` CLI installed and available in your PATH\n2. Install this Python package:\n\n```bash\npip install easykey\n```\n\n### Local Development Installation\n\nIf you're working with the source code:\n\n```bash\ncd python\npip install -e .\n```\n\n## Usage\n\n### Basic Secret Retrieval\n\n```python\nimport easykey\n\n# Get a secret (this will trigger biometric authentication)\nsecret = easykey.secret(\"MySecretName\")\nprint(secret)\n\n# Get a secret with a reason for audit logging\nsecret = easykey.secret(\"MySecretName\", \"Connecting to production database\")\n```\n\n### Listing and Status\n\n```python\nimport easykey\n\n# List all secret names\nsecrets = easykey.list()\nfor secret in secrets:\n print(f\"Secret: {secret['name']}\")\n\n# List secrets with creation timestamps\nsecrets = easykey.list(include_timestamps=True)\nfor secret in secrets:\n print(f\"Secret: {secret['name']}, Created: {secret.get('createdAt', 'Unknown')}\")\n\n# Get vault status\nstatus = easykey.status()\nprint(f\"Total secrets: {status['secrets']}\")\nprint(f\"Last access: {status['last_access']}\")\n```\n\n\n\n## API Reference\n\n### Functions\n\n- **`secret(name, reason=None)`** - Retrieve a secret value\n- **`get_secret(name, reason=None)`** - Alias for `secret()`\n- **`list(include_timestamps=False)`** - List all secrets\n- **`status()`** - Get vault status information\n\n### Parameters\n\n- **`name`** (str): The name/identifier of the secret\n- **`reason`** (str, optional): Reason for the operation (for audit logging)\n- **`include_timestamps`** (bool): Whether to include creation timestamps in list results\n\n\n### Return Values\n\n- **`secret()`** returns the secret value as a string\n- **`list()`** returns a list of dictionaries with secret information\n- **`status()`** returns a dictionary with vault status\n\n### Exceptions\n\nAll functions may raise **`EasyKeyError`** if the underlying CLI operation fails.\n\n## Security Notes\n\n- This package is a thin wrapper around the easykey CLI\n- All security features (biometric authentication, keychain integration) are handled by the CLI\n- Secrets are retrieved through subprocess calls and are not cached in Python\n- The package automatically locates the easykey binary in common installation paths\n\n## Requirements\n\n- macOS (required by the underlying easykey CLI)\n- Python 3.7+\n- easykey CLI installed and accessible\n\n## Quick Start Example\n\n```python\nimport easykey\n\n# Check vault status\nstatus = easykey.status()\nprint(f\"Vault contains {status['secrets']} secrets\")\n\n# List all secrets\nsecrets = easykey.list()\nfor secret in secrets:\n print(f\"Found secret: {secret['name']}\")\n\n# Retrieve a specific secret (requires biometric authentication)\nsecret_value = easykey.secret(\"MySecretName\", \"Accessing for API call\")\nprint(f\"Secret value: {secret_value}\")\n```\n\n**Note:** This is a **read-only** package. To store or manage secrets, use the easykey CLI directly.\n\n## License\n\nMIT License - see the main easykey project for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python wrapper for the easykey CLI - secure keychain access",
"version": "0.1.0",
"project_urls": {
"Bug Reports": "https://github.com/kingofmac/easykey/issues",
"Homepage": "https://github.com/kingofmac/easykey",
"Source": "https://github.com/kingofmac/easykey"
},
"split_keywords": [
"keychain",
" security",
" secrets",
" macos",
" cli",
" wrapper"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "08eedd1ee4dc345db247164cc234d7d523ff71611edb61f525589bc86943dc83",
"md5": "504252b9276fd24667df6d9e5355ea50",
"sha256": "b3426221b33c684aec6ee910e8ad7d2af85b357338cc7803191166a419ce66a5"
},
"downloads": -1,
"filename": "easykey-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "504252b9276fd24667df6d9e5355ea50",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5144,
"upload_time": "2025-08-31T02:24:34",
"upload_time_iso_8601": "2025-08-31T02:24:34.552330Z",
"url": "https://files.pythonhosted.org/packages/08/ee/dd1ee4dc345db247164cc234d7d523ff71611edb61f525589bc86943dc83/easykey-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "70ff5e3a719a38ce60fbee072ca9ed585dbc324ffd07d0fd2ebdc5be5f1e1485",
"md5": "9a49950ce17bcf6eb28463a914554bdd",
"sha256": "bb7fb42f7d4a0ba947e327129f67000dcac65a1cfea71bc7f161fb6905f8c6d0"
},
"downloads": -1,
"filename": "easykey-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "9a49950ce17bcf6eb28463a914554bdd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 5559,
"upload_time": "2025-08-31T02:24:35",
"upload_time_iso_8601": "2025-08-31T02:24:35.868268Z",
"url": "https://files.pythonhosted.org/packages/70/ff/5e3a719a38ce60fbee072ca9ed585dbc324ffd07d0fd2ebdc5be5f1e1485/easykey-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 02:24:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kingofmac",
"github_project": "easykey",
"github_not_found": true,
"lcname": "easykey"
}
JSON
