agent-lock-cli 0.1.1__tar.gz

agent_lock_cli-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-lock contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_lock_cli-0.1.1/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: agent-lock-cli
+Version: 0.1.1
+Summary: Lock agent commands to the local HTTP proxy by running them as the user agentnet.
+License: MIT
+Project-URL: Homepage, https://github.com/jakoes-wu/agent-lock
+Project-URL: Changelog, https://github.com/jakoes-wu/agent-lock/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/jakoes-wu/agent-lock/issues
+Keywords: claude,codex,proxy,firewall,agent,mihomo,clash
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Classifier: Topic :: System :: Networking :: Firewalls
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# agent-lock
+
+**English** | [简体中文](README.zh-CN.md)
+
+[![Release](https://img.shields.io/github/v/release/jakoes-wu/agent-lock)](https://github.com/jakoes-wu/agent-lock/releases)
+[![CI](https://github.com/jakoes-wu/agent-lock/actions/workflows/ci.yml/badge.svg)](https://github.com/jakoes-wu/agent-lock/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agent-lock-cli)](https://pypi.org/project/agent-lock-cli/)
+![Python](https://img.shields.io/badge/python-3.8%2B-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Lock agent commands to the local HTTP proxy by running them as the user `agentnet`.
+
+Codex and Claude, and the programs they start, run as an unprivileged account. The firewall of that account accepts TCP only to the local Clash / mihomo mixed port (`http://127.0.0.1:<mixed-port>`) and to loopback ports you name with `--allow-tcp`. Other TCP, UDP, and ICMP from that account is dropped. The firewall matches the account, not a process path.
+
+`agent-lock` does not start your proxy and it does not edit `multi-codex` or `multi-claude`. netcheck is not this tool. The checks in this repository generate firewall text and classify command output. They do not load nftables, pf, or Windows Firewall on the machine that runs them.
+
+## Install the command
+
+From a clone:
+
+```sh
+git clone https://github.com/jakoes-wu/agent-lock.git
+cd agent-lock
+./install.sh
+```
+
+Or directly:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/jakoes-wu/agent-lock/main/install.sh | sh
+```
+
+The command is installed under `~/.local` (`--prefix` changes that). The installer prints a `PATH` hint and does not edit your shell profile.
+
+From PyPI: `pipx install agent-lock-cli`. Use either pipx or `install.sh`, not both: they both provide an `agent-lock` command. The PyPI project is `agent-lock-cli` because `agentlock` is already published there.
+
+The Homebrew formula is added after the first release asset exists. Until then, use the installer or pipx.
+
+**Verified downloads.** A release publishes `agent-lock-<tag>.tar.gz` and `SHA256SUMS`. The remote installer checks the SHA-256 before it installs. A mismatch stops the install. Branches, and releases that have no such asset, are installed unverified (the installer says so). Set `AGENT_LOCK_REQUIRE_CHECKSUM=1` to refuse those. The checksum detects a corrupted download. It does not prove the GitHub account was not compromised.
+
+`./install.sh` only installs the Python command. It does not create `agentnet` and it does not load a firewall. That is `agent-lock install`, below.
+
+## Lock the account
+
+Point Clash / mihomo at a loopback mixed port, then:
+
+```sh
+sudo agent-lock install
+agent-lock doctor
+agent-lock exec -- true
+```
+
+`install` discovers `mixed-port` from the controller (`GET /configs`). If discovery fails, pass `--port`. A later install without `--allow-tcp` clears the extra loopback list. A loopback service that then dials the network is a second exit beside the proxy.
+
+On Linux and macOS, `install` writes `CLAUDE_CODE_PROCESS_WRAPPER` to the Claude settings it records, after `claude daemon stop --any`. That variable does not apply on Windows. This repository does not write Windows Claude settings, does not change scheduled tasks, and does not store a password. Windows Claude must be started from `runas /user:agentnet`. There is no passwordless `runas`.
+
+`doctor` checks the account, the firewall text, the wrappers, and (where the platform allows it) that a direct connection from `agentnet` fails while the proxy and the owner's own direct TCP still work. `doctor --json` prints schema version 1 and does not print the controller secret. `doctor --repair` reapplies credential ACLs only. It does not change the port and it does not chown launchers.
+
+`uninstall` removes the lock this tool installed. It does not follow or delete the directories you shared, and it does not remove a home directory.
+
+## What you are accepting
+
+- `agentnet` can read the credential files you share (`~/.codex`, `~/.cx`, `~/.claude`, `~/.cc`, and `--share-dir`). That is the cost of running the agent as that user. The macOS Claude keychain is not shared.
+- On macOS, Desktop, Documents, and Downloads (including iCloud Mobile Documents) are TCC-protected. Keep repositories outside those folders. `--share-dir` refuses them.
+- With umask 002, new files in a bind-bin directory become 0664 and are writable by agentnet, and new subdirectories inherit setgid. A new subdirectory created with umask 002 is 2775, so run `bind-bin` on it again. `bind-bin` is Linux only. Launchers themselves are not written by this repository.
+- Unix domain sockets are not filtered. If `agentnet` can connect to the mihomo unix socket, `doctor` fails that check. It does not chmod the socket.
+- A human with the sudo password can undo the firewall.
+- `agentnet` is not an administrator and is not added to `sudo` or Administrators. An existing disabled account is left alone and install fails. An existing enabled account keeps its password.
+
+## Shell completion
+
+Completion is generated from the same argparse parser as the help text. `agent-lock completion <shell>` prints the script even when the lock is not installed.
+
+```sh
+# bash, in ~/.bashrc (macOS bash 3.2, no bash-completion package)
+eval "$(agent-lock completion bash)"
+
+# zsh, after compinit
+eval "$(agent-lock completion zsh)"
+
+# fish
+agent-lock completion fish | source
+
+# PowerShell
+agent-lock completion powershell | Out-String | Add-Content $PROFILE
+```
+
+Filename completion is only offered for `--claude-dir`, `--share-dir`, `--trust-exec`, and the `bind-bin` directory. `--port`, `--allow-tcp`, `--controller`, and the command after `exec --` do not complete filenames.
+
+## Platforms
+
+| | Firewall | Account |
+| --- | --- | --- |
+| Linux | nftables `inet` table, one transaction, output hook on the uid | `useradd` when missing, `passwd -l`, home `/var/lib/agentnet` |
+| macOS | pf `user` rules in an anchor inserted before `anchor "com.apple/*"` | `sysadminctl` when missing |
+| Windows | block rules for literal non-loopback ranges and for loopback ports other than the mixed port | `New-LocalUser`, not an Administrator |
+
+firewalld, a pf `pass quick` already sitting before the Apple anchor, or a Windows policy that does not merge local firewall rules is unsupported (`exit 4`). Install does not run `pfctl -d`. nftables that rejects `destroy table` is also unsupported and install exits 4. nftables 1.0.2 on Ubuntu 22.04 is one of those builds.
+
+## Development
+
+Python 3.8 or newer, standard library only.
+
+```sh
+python3 -m pyflakes src tests
+python3 -m unittest discover -s tests -t tests -v
+shellcheck -s sh install.sh
+```
+
+Tests must pass without root, without nft, without pfctl, and without Windows. Do not run `install.sh` against your real home while developing; the installer tests pass `--prefix` to a temporary directory. Do not run `agent-lock install` on a machine unless you intend to create `agentnet` and load a firewall.

agent_lock_cli-0.1.1/README.md

@@ -0,0 +1,110 @@
+# agent-lock
+
+**English** | [简体中文](README.zh-CN.md)
+
+[![Release](https://img.shields.io/github/v/release/jakoes-wu/agent-lock)](https://github.com/jakoes-wu/agent-lock/releases)
+[![CI](https://github.com/jakoes-wu/agent-lock/actions/workflows/ci.yml/badge.svg)](https://github.com/jakoes-wu/agent-lock/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agent-lock-cli)](https://pypi.org/project/agent-lock-cli/)
+![Python](https://img.shields.io/badge/python-3.8%2B-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Lock agent commands to the local HTTP proxy by running them as the user `agentnet`.
+
+Codex and Claude, and the programs they start, run as an unprivileged account. The firewall of that account accepts TCP only to the local Clash / mihomo mixed port (`http://127.0.0.1:<mixed-port>`) and to loopback ports you name with `--allow-tcp`. Other TCP, UDP, and ICMP from that account is dropped. The firewall matches the account, not a process path.
+
+`agent-lock` does not start your proxy and it does not edit `multi-codex` or `multi-claude`. netcheck is not this tool. The checks in this repository generate firewall text and classify command output. They do not load nftables, pf, or Windows Firewall on the machine that runs them.
+
+## Install the command
+
+From a clone:
+
+```sh
+git clone https://github.com/jakoes-wu/agent-lock.git
+cd agent-lock
+./install.sh
+```
+
+Or directly:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/jakoes-wu/agent-lock/main/install.sh | sh
+```
+
+The command is installed under `~/.local` (`--prefix` changes that). The installer prints a `PATH` hint and does not edit your shell profile.
+
+From PyPI: `pipx install agent-lock-cli`. Use either pipx or `install.sh`, not both: they both provide an `agent-lock` command. The PyPI project is `agent-lock-cli` because `agentlock` is already published there.
+
+The Homebrew formula is added after the first release asset exists. Until then, use the installer or pipx.
+
+**Verified downloads.** A release publishes `agent-lock-<tag>.tar.gz` and `SHA256SUMS`. The remote installer checks the SHA-256 before it installs. A mismatch stops the install. Branches, and releases that have no such asset, are installed unverified (the installer says so). Set `AGENT_LOCK_REQUIRE_CHECKSUM=1` to refuse those. The checksum detects a corrupted download. It does not prove the GitHub account was not compromised.
+
+`./install.sh` only installs the Python command. It does not create `agentnet` and it does not load a firewall. That is `agent-lock install`, below.
+
+## Lock the account
+
+Point Clash / mihomo at a loopback mixed port, then:
+
+```sh
+sudo agent-lock install
+agent-lock doctor
+agent-lock exec -- true
+```
+
+`install` discovers `mixed-port` from the controller (`GET /configs`). If discovery fails, pass `--port`. A later install without `--allow-tcp` clears the extra loopback list. A loopback service that then dials the network is a second exit beside the proxy.
+
+On Linux and macOS, `install` writes `CLAUDE_CODE_PROCESS_WRAPPER` to the Claude settings it records, after `claude daemon stop --any`. That variable does not apply on Windows. This repository does not write Windows Claude settings, does not change scheduled tasks, and does not store a password. Windows Claude must be started from `runas /user:agentnet`. There is no passwordless `runas`.
+
+`doctor` checks the account, the firewall text, the wrappers, and (where the platform allows it) that a direct connection from `agentnet` fails while the proxy and the owner's own direct TCP still work. `doctor --json` prints schema version 1 and does not print the controller secret. `doctor --repair` reapplies credential ACLs only. It does not change the port and it does not chown launchers.
+
+`uninstall` removes the lock this tool installed. It does not follow or delete the directories you shared, and it does not remove a home directory.
+
+## What you are accepting
+
+- `agentnet` can read the credential files you share (`~/.codex`, `~/.cx`, `~/.claude`, `~/.cc`, and `--share-dir`). That is the cost of running the agent as that user. The macOS Claude keychain is not shared.
+- On macOS, Desktop, Documents, and Downloads (including iCloud Mobile Documents) are TCC-protected. Keep repositories outside those folders. `--share-dir` refuses them.
+- With umask 002, new files in a bind-bin directory become 0664 and are writable by agentnet, and new subdirectories inherit setgid. A new subdirectory created with umask 002 is 2775, so run `bind-bin` on it again. `bind-bin` is Linux only. Launchers themselves are not written by this repository.
+- Unix domain sockets are not filtered. If `agentnet` can connect to the mihomo unix socket, `doctor` fails that check. It does not chmod the socket.
+- A human with the sudo password can undo the firewall.
+- `agentnet` is not an administrator and is not added to `sudo` or Administrators. An existing disabled account is left alone and install fails. An existing enabled account keeps its password.
+
+## Shell completion
+
+Completion is generated from the same argparse parser as the help text. `agent-lock completion <shell>` prints the script even when the lock is not installed.
+
+```sh
+# bash, in ~/.bashrc (macOS bash 3.2, no bash-completion package)
+eval "$(agent-lock completion bash)"
+
+# zsh, after compinit
+eval "$(agent-lock completion zsh)"
+
+# fish
+agent-lock completion fish | source
+
+# PowerShell
+agent-lock completion powershell | Out-String | Add-Content $PROFILE
+```
+
+Filename completion is only offered for `--claude-dir`, `--share-dir`, `--trust-exec`, and the `bind-bin` directory. `--port`, `--allow-tcp`, `--controller`, and the command after `exec --` do not complete filenames.
+
+## Platforms
+
+| | Firewall | Account |
+| --- | --- | --- |
+| Linux | nftables `inet` table, one transaction, output hook on the uid | `useradd` when missing, `passwd -l`, home `/var/lib/agentnet` |
+| macOS | pf `user` rules in an anchor inserted before `anchor "com.apple/*"` | `sysadminctl` when missing |
+| Windows | block rules for literal non-loopback ranges and for loopback ports other than the mixed port | `New-LocalUser`, not an Administrator |
+
+firewalld, a pf `pass quick` already sitting before the Apple anchor, or a Windows policy that does not merge local firewall rules is unsupported (`exit 4`). Install does not run `pfctl -d`. nftables that rejects `destroy table` is also unsupported and install exits 4. nftables 1.0.2 on Ubuntu 22.04 is one of those builds.
+
+## Development
+
+Python 3.8 or newer, standard library only.
+
+```sh
+python3 -m pyflakes src tests
+python3 -m unittest discover -s tests -t tests -v
+shellcheck -s sh install.sh
+```
+
+Tests must pass without root, without nft, without pfctl, and without Windows. Do not run `install.sh` against your real home while developing; the installer tests pass `--prefix` to a temporary directory. Do not run `agent-lock install` on a machine unless you intend to create `agentnet` and load a firewall.

agent_lock_cli-0.1.1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-lock-cli"
+dynamic = ["version"]
+description = "Lock agent commands to the local HTTP proxy by running them as the user agentnet."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+keywords = ["claude", "codex", "proxy", "firewall", "agent", "mihomo", "clash"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+    "Topic :: System :: Networking :: Firewalls",
+]
+
+[project.scripts]
+agent-lock = "agent_lock.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/jakoes-wu/agent-lock"
+Changelog = "https://github.com/jakoes-wu/agent-lock/blob/main/CHANGELOG.md"
+Issues = "https://github.com/jakoes-wu/agent-lock/issues"
+
+[tool.setuptools.dynamic]
+version = {attr = "agent_lock.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

agent_lock_cli-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_lock_cli-0.1.1/src/agent_lock/__init__.py

@@ -0,0 +1,3 @@
+"""Lock agent commands to the local HTTP proxy by running them as agentnet."""
+
+__version__ = "0.1.1"

agent_lock_cli-0.1.1/src/agent_lock/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

agent_lock_cli-0.1.1/src/agent_lock/allow.py

@@ -0,0 +1,40 @@
+"""--allow-tcp values. Only 127.0.0.1:PORT and ::1:PORT."""
+
+import argparse
+import re
+
+_VALUE = re.compile(r"^(127\.0\.0\.1|::1):([0-9]+)$")
+
+
+def parse_allow_tcp_value(value):
+    """Return (host, port) or raise ValueError. Used by firewall renderers."""
+    match = _VALUE.match(value or "")
+    if not match:
+        raise ValueError(value)
+    port = int(match.group(2))
+    if match.group(2) != str(port):
+        # Reject leading zeros so the stored form is canonical.
+        raise ValueError(value)
+    if port < 1 or port > 65535:
+        raise ValueError(value)
+    return match.group(1), port
+
+
+def allow_tcp_arg(value):
+    """argparse type. Illegal values are exit 2."""
+    try:
+        host, port = parse_allow_tcp_value(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(
+            "must be 127.0.0.1:PORT or ::1:PORT (port 1-65535), not {!r}".format(value))
+    return "{}:{}".format(host, port)
+
+
+def port_arg(value):
+    try:
+        port = int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError("port must be an integer")
+    if str(port) != str(value).lstrip("+") or port < 1 or port > 65535:
+        raise argparse.ArgumentTypeError("port must be 1-65535")
+    return port

agent_lock_cli-0.1.1/src/agent_lock/cli.py

@@ -0,0 +1,181 @@
+"""agent-lock command line. Help text and examples come from this module."""
+
+import argparse
+import sys
+
+from . import __version__
+from .allow import allow_tcp_arg, port_arg
+from .completion import SHELLS, script
+from .errors import AgentLockError
+from .install import cmd_bind_bin, cmd_doctor, cmd_exec, cmd_install, cmd_uninstall
+
+COMMAND_GROUPS = (
+    ("Setup", (
+        ("install", "install the account, firewall, and wrappers"),
+        ("uninstall", "remove the lock and keep linked directories"),
+        ("bind-bin", "mark a directory setgid for new launchers"),
+        ("completion", "print a shell completion script"),
+    )),
+    ("Everyday", (
+        ("doctor", "check the lock and repair cleared ACLs"),
+        ("exec", "run one command as agentnet"),
+    )),
+)
+COMMAND_SUMMARY = {name: summary for _title, commands in COMMAND_GROUPS for name, summary in commands}
+
+TOP_EXAMPLES = (
+    ("agent-lock install", "install the lock"),
+    ("agent-lock doctor", "check the lock"),
+    ("agent-lock exec -- true", "run one command as agentnet"),
+    ("agent-lock completion bash", "print a bash script"),
+)
+
+COMMAND_EXAMPLES = {
+    "install": (
+        ("agent-lock install", "install lock"),
+        ("agent-lock install --port 7897 --allow-tcp 127.0.0.1:11434", "pin the port"),
+        ("agent-lock install --controller 127.0.0.1:9097 --secret-stdin", "read secret"),
+        ("agent-lock install --share-dir ~/.cx --trust-exec ~/bin", "share paths"),
+    ),
+    "uninstall": (
+        ("agent-lock uninstall", "remove the lock"),
+        ("agent-lock uninstall", "safe to repeat"),
+    ),
+    "doctor": (
+        ("agent-lock doctor", "run every check"),
+        ("agent-lock doctor --json", "print version 1 JSON"),
+        ("agent-lock doctor --repair", "restore cleared ACLs"),
+    ),
+    "exec": (
+        ("agent-lock exec -- true", "run true as agentnet"),
+        ("agent-lock exec -- curl -I https://example.com", "only via the proxy"),
+        ("agent-lock exec -- git status", "run git as agentnet"),
+    ),
+    "bind-bin": (
+        ("sudo agent-lock bind-bin ~/.local/bin", "setgid this directory"),
+        ("sudo agent-lock bind-bin /tmp/bin", "clear group write again"),
+    ),
+    "completion": (
+        ("eval \"$(agent-lock completion bash)\"", "add this to ~/.bashrc"),
+        ("eval \"$(agent-lock completion zsh)\"", "run this after compinit"),
+        ("agent-lock completion fish | source", "load the fish script"),
+        ("agent-lock completion powershell", "print the PowerShell script"),
+    ),
+}
+
+ALLOW_TCP_HELP = (
+    "loopback TCP port to allow (127.0.0.1:PORT or ::1:PORT). "
+    "A loopback service that then dials the network is a second exit beside the proxy."
+)
+
+
+def _examples_text(examples):
+    """examples: epilog. Command lines are padded to the longest plus two."""
+    width = max(len(command) for command, _summary in examples) + 2
+    lines = ["examples:"]
+    lines.extend("  {}{}".format(command.ljust(width), summary) for command, summary in examples)
+    return "\n".join(lines) + "\n"
+
+
+def _grouped_commands_text():
+    width = max(len(name) for name in COMMAND_SUMMARY) + 2
+    lines = []
+    for title, commands in COMMAND_GROUPS:
+        lines.append("{}:".format(title))
+        lines.extend("  {}{}".format(name.ljust(width), summary) for name, summary in commands)
+        lines.append("")
+    return "\n".join(lines).rstrip("\n")
+
+
+HELP_EXAMPLES = _examples_text(TOP_EXAMPLES) + "\nRun agent-lock COMMAND -h for more examples.\n"
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="agent-lock",
+        allow_abbrev=False,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="Lock agent commands to the local HTTP proxy by running them as the user agentnet.\n\n"
+        + _grouped_commands_text(),
+        epilog=HELP_EXAMPLES,
+    )
+    parser.add_argument("--version", action="version", version="%(prog)s " + __version__)
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+    sub.required = True
+
+    install = sub.add_parser("install", description=COMMAND_SUMMARY["install"], allow_abbrev=False)
+    install.add_argument("--port", type=port_arg, help="mixed port; required when discovery fails")
+    install.add_argument("--controller", help="loopback controller (host:port or unix:PATH)")
+    install.add_argument("--secret-stdin", action="store_true", help="read one secret line from stdin")
+    install.add_argument("--claude-dir", action="append", default=None, help="extra Claude settings directory")
+    install.add_argument("--share-dir", action="append", default=None, help="extra directory to share with agentnet")
+    install.add_argument("--trust-exec", action="append", default=None, help="program or directory agentnet may execute")
+    install.add_argument("--allow-tcp", action="append", default=None, type=allow_tcp_arg, help=ALLOW_TCP_HELP)
+
+    sub.add_parser("uninstall", description=COMMAND_SUMMARY["uninstall"], allow_abbrev=False)
+
+    doctor = sub.add_parser("doctor", description=COMMAND_SUMMARY["doctor"], allow_abbrev=False)
+    doctor.add_argument("--json", action="store_true", help="print version 1 JSON")
+    doctor.add_argument("--repair", action="store_true", help="reapply credential ACLs; does not change the port")
+
+    sub.add_parser("exec", description=COMMAND_SUMMARY["exec"], allow_abbrev=False)
+
+    bind = sub.add_parser("bind-bin", description=COMMAND_SUMMARY["bind-bin"], allow_abbrev=False)
+    bind.add_argument("path", metavar="PATH", help="directory to mark setgid for the agentnet group")
+
+    completion = sub.add_parser("completion", description=COMMAND_SUMMARY["completion"], allow_abbrev=False)
+    completion.add_argument("shell", choices=SHELLS, help="bash, zsh, fish, or powershell")
+
+    for name, subparser in sub.choices.items():
+        subparser.formatter_class = argparse.RawDescriptionHelpFormatter
+        subparser.epilog = _examples_text(COMMAND_EXAMPLES[name])
+        subparser.allow_abbrev = False
+    return parser
+
+
+def _split_exec(argv):
+    """Drop the command tail at the first --. Flags such as -h stay on the parser side."""
+    if not argv or argv[0] != "exec":
+        return argv, None
+    if "--" not in argv:
+        return argv, None
+    index = argv.index("--")
+    return argv[:index] or ["exec"], argv[index + 1:]
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    argv = list(argv)
+    argv, tail = _split_exec(argv)
+    try:
+        parser = build_parser()
+        if argv and argv[0] == "completion":
+            # Print the script even when agent-lock is not installed.
+            args = parser.parse_args(argv)
+            sys.stdout.write(script(args.shell, parser))
+            return 0
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        code = exc.code
+        if code is None:
+            return 0
+        return int(code)
+    try:
+        if args.command == "install":
+            return cmd_install(args)
+        if args.command == "uninstall":
+            return cmd_uninstall(args)
+        if args.command == "doctor":
+            return cmd_doctor(args)
+        if args.command == "exec":
+            return cmd_exec(tail)
+        if args.command == "bind-bin":
+            return cmd_bind_bin(args)
+        if args.command == "completion":
+            sys.stdout.write(script(args.shell, parser))
+            return 0
+    except AgentLockError as exc:
+        sys.stderr.write("agent-lock: {}\n".format(exc))
+        return int(exc.code)
+    return 2