ZeptapDocs
Commands

acquire

Hold a phone so no other agent, MCP client or Zeptap's own chat can drive it. Prints the lease id.

Usage

zeptap acquire --reason <task>

Options

OptionDescription
--reason <task>Required. What you're doing. Others see it when they're refused
--label <who>Who holds the phone, such as an agent session id
-p, --phone <id or name>The phone to hold. Env: ZEPTAP_PHONE
--idle-timeout <duration>Release the lease after this long without a command (default 600 seconds)
--wait <duration>If the phone is leased, keep trying for this long instead of failing
--forceTake the phone over from the current holder. Use it only when that lease is stale

Also takes --json. See Global options.

Details

  • stdout is only the lease id. The message goes to stderr, so LEASE=$(zeptap acquire --reason "...") works.
  • Pass the id with -l <id> on every command, or set ZEPTAP_LEASE.
  • While a phone is leased, calls from anyone else are refused with exit code 9: other zeptap commands, MCP agents and Zeptap's own chat. The refusal says who holds the phone, for what, and when they last used it.
  • A lease ends with release, after --idle-timeout without a command, or when Zeptap quits. A crashed agent can't block a phone for long.
  • --wait checks every 2 seconds. Without it, a leased phone fails at once with exit code 9.

Examples

$ zeptap acquire --reason "reply to Anna in Messages"            # prints e.g. 7
$ zeptap acquire --reason "warm up @sara_runs" --label codex-4411 -p A1B2 --wait 2m
$ LEASE=$(zeptap acquire --reason "check notifications")
$ zeptap look -l "$LEASE"

MCP tool

None. Leases are a CLI feature, but MCP agents are refused while a phone is leased.

On this page