| Name | hitl-cli JSON |
| Version |
1.2.1
JSON |
| download |
| home_page | None |
| Summary | Command-line interface and SDK for Human-in-the-Loop services. |
| upload_time | 2025-10-26 12:57:50 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
agent
ai
cli
hitl
human-in-the-loop
mcp
sdk
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# HITL-CLI: Human-in-the-Loop Command-Line Interface and SDK
**hitl-cli** is the official reference MCP client for the [Human-in-the-Loop (HITL) mobile application](https://hitlrelay.app). It provides a powerful command-line interface (CLI) and Python SDK to programmatically request input from, and send notifications to, a human user via their mobile device.
It features zero-config, secure authentication using OAuth 2.1 and supports end-to-end encryption (E2EE) for confidential interactions.
## Features
- **Command-Line Interface:** Easily send HITL requests from your terminal or shell scripts.
- **Python SDK:** Integrate human-in-the-loop workflows directly into your Python applications.
- **Secure by Default:** Uses modern OAuth 2.1 with PKCE for user authentication. No manual client setup needed.
- **End-to-End Encryption:** A local proxy mode enables E2EE for use with tools like Claude Desktop, ensuring the server only handles encrypted data.
- **Service Authentication:** Supports API key authentication for non-interactive environments (e.g., CI/CD, backend services).
## 1. Installation
Install `hitl-cli` from PyPI using `pip` (or your preferred Python package manager):
```bash
pip install hitl-cli
```
## 2. Authentication
You can authenticate in two ways: OAuth 2.1 (for users) or API Keys (for services).
### Option A: OAuth 2.1 (Recommended for Users)
This is the standard method for interactive use. The `login` command will open your browser to authenticate and securely store your credentials.
1. **Run the login command:**
```bash
hitl-cli login --name "My Workstation"
```
*This will open a browser window for you to log in or sign up.*
2. **Authenticate in the browser.**
3. Upon success, your credentials will be securely stored, and your CLI will be ready to use.
### Option B: API Key (for Services and Automation)
For non-interactive environments, you can authenticate by setting an environment variable.
```bash
export HITL_API_KEY="your_api_key_here"
# Now you can use the CLI without the login step
hitl-cli notify --message "The nightly build has completed."
```
## 3. Usage Patterns
### A. As a Command-Line Tool
Quickly request human input or send notifications directly from your terminal.
**Example: Requesting Input**
```bash
# Request a simple confirmation
hitl-cli request --prompt "Do you approve the deployment to production?"
# Provide multiple choices
hitl-cli request --prompt "Which environment to deploy?" --choice "Staging" --choice "Production"
```
**Example: Sending a Notification**
```bash
hitl-cli notify --message "The data processing job has started."
```
### B. As a Python SDK
Integrate HITL workflows into your Python applications using the `HITL` class.
```python
import asyncio
from hitl_cli import HITL
async def main():
# The SDK automatically uses your configured credentials (OAuth or API Key)
hitl = HITL()
try:
# Request input and wait for the response
user_response = await hitl.request_input(
"Do you want to proceed with the database migration?",
choices=["Yes", "No", "Postpone"]
)
print(f"Human response: {user_response}")
if user_response == "Yes":
await hitl.notify("Database migration started.")
# ... run migration ...
await hitl.notify_completion("The database migration is complete!")
except Exception as e:
print(f"An error occurred: {e}")
if __name__ == "__main__":
asyncio.run(main())
```
### C. End-to-End Encryption with a Local Proxy
For maximum security, `hitl-cli` can act as a local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) proxy. This allows tools like Claude Code to interact with a human while ensuring that the prompt and response are end-to-end encrypted. The HITL server only relays the encrypted data and never sees the plaintext content.
1. **Authenticate first:**
**Option A: OAuth (Interactive)**
```bash
hitl-cli login --name "My E2EE Agent"
```
**Option B: API Key (Services/Automation)**
```bash
export HITL_API_KEY="your_api_key_here"
```
2. **Configure your MCP client (e.g., Claude Desktop's `mcp_servers.json`):**
```json
{
"mcpServers": {
"human": {
"command": "hitl-cli",
"args": ["proxy", "https://hitlrelay.app/mcp-server/mcp/"],
"env": {
"HITL_API_KEY": "your_api_key_here"
}
}
}
}
```
The proxy will automatically encrypt the request and decrypt the response. The llm will still use the unecrypted enpoints and the hit-cli proxy will use the endpoints ending in e2ee
```python
human.request_human_input(prompt="Please provide the API key for the staging environment.")
```
### D. Continuous Interaction Hook for Claude Code
The `hitl-hook-review-and-continue` hook provides a powerful way to create a continuous interaction loop with Claude Code. When Claude finishes a task, this hook intercepts the stop event, asks for your confirmation via the HITL app, and feeds your response back to Claude as new instructions.
**Setup:**
Add the following to your Claude Code settings file:
- `~/.claude/settings.json` (user-level, affects all projects)
- `.claude/settings.local.json` (project-level, gitignored)
```json
{
"hooks": {
"Stop": [
{
"matcher": ".*",
"hooks": [
{
"type": "command",
"command": "uvx --from hitl-cli hitl-hook-review-and-continue"
}
]
}
]
}
}
```
**How it works:**
- When Claude Code finishes responding, the hook executes
- A prompt appears on your HITL mobile app
- You can review what Claude did and provide feedback
- Your response is fed back to Claude as new instructions
- This creates an interactive review-and-continue workflow for continuos operation with claude code
For more details on hooks, see the [Claude Code hooks documentation](https://docs.claude.com/en/docs/claude-code/hooks).
This turns `hitl-cli` into a remote control for your AI assistant.
### E. Codex CLI Notifications
The `hitl-codex-notify` hook enables you to receive notifications on your HITL mobile app when Codex CLI completes a task. Unlike the Claude Code hook, this is a fire-and-forget notification system that keeps you informed about Codex activity without allowing interaction.
**Setup:**
Add the following to your Codex configuration file at `~/.codex/config.toml`:
```toml
notify = ["hitl-codex-notify"]
```
**How it works:**
- When Codex CLI completes a turn, the hook executes automatically
- A notification appears on your HITL mobile app with:
- The task that was performed
- Codex's completion message
- The working directory
- A session identifier
- No interaction required - pure notification
**Example notification:**
```
🤖 Codex Turn Complete
📝 Task: Rename `foo` to `bar` and update the callsites.
✅ Result: Rename complete and verified `cargo build` succeeds.
📁 Directory: /Users/alice/projects/example
🔗 Session: b5f6c1c2...
```
This is ideal for keeping track of Codex activity while you're away from your desk or working on other tasks.
Raw data
{
"_id": null,
"home_page": null,
"name": "hitl-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "agent, ai, cli, hitl, human-in-the-loop, mcp, sdk",
"author": null,
"author_email": "HITL CLI Team <contact@hitlrelay.app>",
"download_url": "https://files.pythonhosted.org/packages/fe/b8/c24ceecc17a19cc56b53a34297e9cc11cbcac7f83486ead2f323122ecbdd/hitl_cli-1.2.1.tar.gz",
"platform": null,
"description": "\n# HITL-CLI: Human-in-the-Loop Command-Line Interface and SDK\n\n**hitl-cli** is the official reference MCP client for the [Human-in-the-Loop (HITL) mobile application](https://hitlrelay.app). It provides a powerful command-line interface (CLI) and Python SDK to programmatically request input from, and send notifications to, a human user via their mobile device.\n\nIt features zero-config, secure authentication using OAuth 2.1 and supports end-to-end encryption (E2EE) for confidential interactions.\n\n## Features\n\n- **Command-Line Interface:** Easily send HITL requests from your terminal or shell scripts.\n- **Python SDK:** Integrate human-in-the-loop workflows directly into your Python applications.\n- **Secure by Default:** Uses modern OAuth 2.1 with PKCE for user authentication. No manual client setup needed.\n- **End-to-End Encryption:** A local proxy mode enables E2EE for use with tools like Claude Desktop, ensuring the server only handles encrypted data.\n- **Service Authentication:** Supports API key authentication for non-interactive environments (e.g., CI/CD, backend services).\n\n## 1. Installation\n\nInstall `hitl-cli` from PyPI using `pip` (or your preferred Python package manager):\n\n```bash\npip install hitl-cli\n```\n\n## 2. Authentication\n\nYou can authenticate in two ways: OAuth 2.1 (for users) or API Keys (for services).\n\n### Option A: OAuth 2.1 (Recommended for Users)\n\nThis is the standard method for interactive use. The `login` command will open your browser to authenticate and securely store your credentials.\n\n1. **Run the login command:**\n ```bash\n hitl-cli login --name \"My Workstation\"\n ```\n *This will open a browser window for you to log in or sign up.*\n\n2. **Authenticate in the browser.**\n\n3. Upon success, your credentials will be securely stored, and your CLI will be ready to use.\n\n### Option B: API Key (for Services and Automation)\n\nFor non-interactive environments, you can authenticate by setting an environment variable.\n\n```bash\nexport HITL_API_KEY=\"your_api_key_here\"\n\n# Now you can use the CLI without the login step\nhitl-cli notify --message \"The nightly build has completed.\"\n```\n\n## 3. Usage Patterns\n\n### A. As a Command-Line Tool\n\nQuickly request human input or send notifications directly from your terminal.\n\n**Example: Requesting Input**\n```bash\n# Request a simple confirmation\nhitl-cli request --prompt \"Do you approve the deployment to production?\"\n\n# Provide multiple choices\nhitl-cli request --prompt \"Which environment to deploy?\" --choice \"Staging\" --choice \"Production\"\n```\n\n**Example: Sending a Notification**\n```bash\nhitl-cli notify --message \"The data processing job has started.\"\n```\n\n### B. As a Python SDK\n\nIntegrate HITL workflows into your Python applications using the `HITL` class.\n\n```python\nimport asyncio\nfrom hitl_cli import HITL\n\nasync def main():\n # The SDK automatically uses your configured credentials (OAuth or API Key)\n hitl = HITL()\n\n try:\n # Request input and wait for the response\n user_response = await hitl.request_input(\n \"Do you want to proceed with the database migration?\",\n choices=[\"Yes\", \"No\", \"Postpone\"]\n )\n\n print(f\"Human response: {user_response}\")\n\n if user_response == \"Yes\":\n await hitl.notify(\"Database migration started.\")\n # ... run migration ...\n await hitl.notify_completion(\"The database migration is complete!\")\n\n except Exception as e:\n print(f\"An error occurred: {e}\")\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### C. End-to-End Encryption with a Local Proxy\n\nFor maximum security, `hitl-cli` can act as a local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) proxy. This allows tools like Claude Code to interact with a human while ensuring that the prompt and response are end-to-end encrypted. The HITL server only relays the encrypted data and never sees the plaintext content.\n\n1. **Authenticate first:**\n\n **Option A: OAuth (Interactive)**\n ```bash\n hitl-cli login --name \"My E2EE Agent\"\n ```\n\n **Option B: API Key (Services/Automation)**\n ```bash\n export HITL_API_KEY=\"your_api_key_here\"\n ```\n\n2. **Configure your MCP client (e.g., Claude Desktop's `mcp_servers.json`):**\n ```json\n {\n \"mcpServers\": {\n \"human\": {\n \"command\": \"hitl-cli\",\n \"args\": [\"proxy\", \"https://hitlrelay.app/mcp-server/mcp/\"],\n \"env\": {\n \"HITL_API_KEY\": \"your_api_key_here\"\n }\n }\n }\n }\n ```\nThe proxy will automatically encrypt the request and decrypt the response. The llm will still use the unecrypted enpoints and the hit-cli proxy will use the endpoints ending in e2ee\n\n ```python\n human.request_human_input(prompt=\"Please provide the API key for the staging environment.\")\n ```\n\n### D. Continuous Interaction Hook for Claude Code\n\nThe `hitl-hook-review-and-continue` hook provides a powerful way to create a continuous interaction loop with Claude Code. When Claude finishes a task, this hook intercepts the stop event, asks for your confirmation via the HITL app, and feeds your response back to Claude as new instructions.\n\n**Setup:**\n\nAdd the following to your Claude Code settings file:\n- `~/.claude/settings.json` (user-level, affects all projects)\n- `.claude/settings.local.json` (project-level, gitignored)\n\n```json\n{\n \"hooks\": {\n \"Stop\": [\n {\n \"matcher\": \".*\",\n \"hooks\": [\n {\n \"type\": \"command\",\n \"command\": \"uvx --from hitl-cli hitl-hook-review-and-continue\"\n }\n ]\n }\n ]\n }\n}\n```\n\n\n\n**How it works:**\n- When Claude Code finishes responding, the hook executes\n- A prompt appears on your HITL mobile app\n- You can review what Claude did and provide feedback\n- Your response is fed back to Claude as new instructions\n- This creates an interactive review-and-continue workflow for continuos operation with claude code\n\nFor more details on hooks, see the [Claude Code hooks documentation](https://docs.claude.com/en/docs/claude-code/hooks).\n\nThis turns `hitl-cli` into a remote control for your AI assistant.\n\n### E. Codex CLI Notifications\n\nThe `hitl-codex-notify` hook enables you to receive notifications on your HITL mobile app when Codex CLI completes a task. Unlike the Claude Code hook, this is a fire-and-forget notification system that keeps you informed about Codex activity without allowing interaction.\n\n**Setup:**\n\nAdd the following to your Codex configuration file at `~/.codex/config.toml`:\n\n```toml\nnotify = [\"hitl-codex-notify\"]\n```\n\n**How it works:**\n- When Codex CLI completes a turn, the hook executes automatically\n- A notification appears on your HITL mobile app with:\n - The task that was performed\n - Codex's completion message\n - The working directory\n - A session identifier\n- No interaction required - pure notification\n\n**Example notification:**\n```\n\ud83e\udd16 Codex Turn Complete\n\n\ud83d\udcdd Task: Rename `foo` to `bar` and update the callsites.\n\u2705 Result: Rename complete and verified `cargo build` succeeds.\n\ud83d\udcc1 Directory: /Users/alice/projects/example\n\ud83d\udd17 Session: b5f6c1c2...\n```\n\nThis is ideal for keeping track of Codex activity while you're away from your desk or working on other tasks.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Command-line interface and SDK for Human-in-the-Loop services.",
"version": "1.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/slaser79/hitl-cli/issues",
"Homepage": "https://github.com/slaser79/hitl-cli",
"Repository": "https://github.com/slaser79/hitl-cli"
},
"split_keywords": [
"agent",
" ai",
" cli",
" hitl",
" human-in-the-loop",
" mcp",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "19b54223ea81f13244c62f302a5509f14fbc29e704ee6e4b97606a6c9e866beb",
"md5": "a605477adbef2e7370d89b15549bad8e",
"sha256": "44f14674d9c20a09f7f07dcae46aa967fd75287e4de3f3cc8774561c3fdb970c"
},
"downloads": -1,
"filename": "hitl_cli-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a605477adbef2e7370d89b15549bad8e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 33269,
"upload_time": "2025-10-26T12:57:49",
"upload_time_iso_8601": "2025-10-26T12:57:49.594323Z",
"url": "https://files.pythonhosted.org/packages/19/b5/4223ea81f13244c62f302a5509f14fbc29e704ee6e4b97606a6c9e866beb/hitl_cli-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "feb8c24ceecc17a19cc56b53a34297e9cc11cbcac7f83486ead2f323122ecbdd",
"md5": "953915aa8a7a67bd5fc9e84f1ccf47c8",
"sha256": "a90954730be5407c9f449e735a13ae92b4f3f55cd76745bbd4ce7b6b571b5300"
},
"downloads": -1,
"filename": "hitl_cli-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "953915aa8a7a67bd5fc9e84f1ccf47c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 124461,
"upload_time": "2025-10-26T12:57:50",
"upload_time_iso_8601": "2025-10-26T12:57:50.636762Z",
"url": "https://files.pythonhosted.org/packages/fe/b8/c24ceecc17a19cc56b53a34297e9cc11cbcac7f83486ead2f323122ecbdd/hitl_cli-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 12:57:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "slaser79",
"github_project": "hitl-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hitl-cli"
}
