mech.app

Posted on Oct 28 Originally published at mech.app

Proc-CLI: What an Agent-Friendly Process Manager Reveals About CLI Design for Autonomous Tools

#agents #automation #cli #softwaredevelopment

Most CLI tools assume a human is reading the output. Colors, ASCII tables, and prose error messages optimize for terminal sessions, not programmatic consumption. When an agent needs to kill a process on port 3000, parse the result, and decide what to do next, those assumptions break.

Proc-CLI is a process and port management tool designed with agents as first-class consumers. It exposes what changes when you stop designing for grep pipelines and start designing for autonomous tool calls.

The Agent-Friendly Contract

Traditional process managers like lsof, ps, and netstat return unstructured text. Agents can parse it, but every error case requires custom handling. Proc-CLI makes three commitments:

Structured output by default: JSON mode for every command, not a flag you remember to add.
Predictable exit codes: Zero on success, non-zero on failure, with distinct codes for different failure modes.
Idempotency guarantees: Running the same command twice produces the same result without side effects.

These are not novel ideas. They are table stakes for tools that agents will call hundreds of times per day without human supervision.

Semantic Targeting

Proc-CLI uses a target syntax that collapses multiple lookup strategies into one argument:

proc kill :3000        # Port 3000
proc kill 1234         # PID 1234
proc kill node         # Process name
proc kill node --in .  # Scoped to current directory

The leading colon signals a port. A bare number is a PID. Anything else is a process name. This removes the need for agents to choose between -p, --port, --pid, or --name flags based on context.

For agents, this means one fewer decision tree in the tool-call logic. The agent passes a target string and the CLI figures out what it means.

Concurrent Access and State Consistency

When multiple agents query or modify process state simultaneously, race conditions appear. Proc-CLI does not solve this at the process manager level (the OS owns that), but it does expose the problem clearly.

If an agent runs proc kill :3000 and the process respawns before the command returns, the exit code reflects what happened. The JSON output includes:

Processes matched
Processes terminated
Processes that failed to terminate
Processes that reappeared during execution

An agent can check terminated_count against matched_count and decide whether to retry, escalate, or log the discrepancy.

Error Recovery Primitives

Partial failures are common in process management. A port might be held by multiple processes. A process might ignore SIGTERM and require SIGKILL. A process might terminate but leave a socket in TIME_WAIT.

Proc-CLI returns structured error objects for each target:

{
  "target": ":3000",
  "matched": 2,
  "terminated": 1,
  "failed": [
    {
      "pid": 5678,
      "name": "node",
      "reason": "permission_denied"
    }
  ]
}

This lets agents implement retry logic with backoff, escalate to privileged commands, or surface the failure to a human operator. The reason field is an enum, not a prose string, so agents can switch on it.

Dry-Run and Confirmation Modes

Agents need to preview destructive actions before executing them. Proc-CLI supports --dry-run for every command that modifies state:

proc kill :3000 --dry-run

This returns the same JSON structure as the real command, but with would_terminate instead of terminated. The agent can log the preview, check it against policy, and then run the real command if approved.

Interactive confirmation (proc kill :3000 asks before killing) is disabled in non-TTY contexts. Agents get deterministic behavior without needing to pipe yes or set environment variables.

Observability Hooks

Proc-CLI exposes a --json flag that works with every command. This is not a debug mode. It is the primary interface for agents.

The JSON schema is versioned. Breaking changes increment the major version. Agents can check the schema version in the output and fail fast if the contract changes.

For long-running operations like proc wait :3000, the tool streams newline-delimited JSON instead of blocking until completion. Agents can process each event as it arrives and cancel the operation if needed.

Deployment Shape

Proc-CLI is a single binary with no runtime dependencies. It works on macOS, Linux, and Windows without requiring elevated privileges for read-only operations.

For containerized agents, this means:

No need to install Python, Node, or Ruby to run a process manager.
No need to mount /proc or /sys with special permissions.
No need to run the agent container as root.

The binary is small enough (under 10 MB) to include in base images without bloating them.

Failure Modes

Proc-CLI can fail in ways that are invisible to agents if you do not check the right fields:

Failure Mode	Symptom	Detection
Process respawns after kill	Exit code 0, but port still occupied	Check `proc info :3000` after kill
Partial termination	Some PIDs killed, others not	Compare `matched` vs `terminated` counts
Permission denied	Non-zero exit, but unclear why	Parse `reason` field in failed array
Stale socket	Port shows as occupied, but no process	Check `listening` vs `bound` in JSON

Agents should always parse the JSON output, not just check the exit code. A zero exit means the command ran, not that it achieved the desired state.

When to Use Proc-CLI

Use it when:

Agents need to manage processes as part of a larger workflow (deploy, test, rollback).
You want one tool that works the same on developer laptops and production servers.
You need structured output without writing custom parsers for lsof and ps.

Avoid it when:

You need advanced process supervision (use systemd, supervisord, or pm2).
You need to manage processes across multiple machines (use a cluster orchestrator).
You need real-time process metrics (use a monitoring agent, not a CLI).

Technical Verdict

Proc-CLI demonstrates that agent-friendly CLI design is not about adding a --json flag to existing tools. It requires rethinking error handling, output contracts, and state reporting from the ground up.

The semantic targeting syntax reduces the cognitive load on agents. The structured error objects enable precise retry logic. The dry-run mode lets agents preview destructive actions without side effects.

If you are building tools that agents will call, study how Proc-CLI handles partial failures, concurrent access, and non-TTY contexts. These are the sharp edges where most CLIs fail when agents start using them at scale.

DEV Community