agentknock pairing remove

agentknock pairing remove removes an active pairing from the phone and this client. Use it when this client should no longer make requests through that pairing.

agentknock pairing remove [--force]

Remove a pairing

Without --force, the phone must be reachable. Agentknock asks it to remove the pairing and waits for an authenticated response before deleting the local record. It then sends a final confirmation that local removal succeeded and prints a success message to standard output. A failure to deliver that final confirmation doesn’t undo removal or turn it into a command failure.

An active pairing is required. If there is no pairing, the command returns an error. If a pairing is pending, it returns an error and leaves that attempt unchanged; use pairing abort to discard it.

Remove only the local pairing

--force deletes only the local pairing without contacting the phone or relay. Use it when normal removal can’t complete, for example when the phone is unavailable or has already revoked the client:

agentknock pairing remove --force

This option can remove either an active or a pending pairing. It also allows recovery from a malformed pairing file, because it deletes the file without reading its contents. File deletion can still fail if filesystem permissions prevent it. If no local pairing exists, it returns an error.

Any pairing record on the phone remains unchanged. To end that client’s access on the phone, revoke it there.

Waiting, interruption, and errors

Normal removal reports progress and elapsed time to standard error every 30 seconds. See connection retries for shared waiting behavior.

If an error or interruption occurs before Agentknock authenticates the phone’s removal response, the local pairing is retained. The phone may already have removed its record. Check the phone before retrying, and use --force if only the local record remains.

If the phone confirms removal but the local file can’t be deleted, Agentknock reports that distinction. Resolve the local file problem, then use --force to remove the remaining record. If another process replaced the pairing during the request, Agentknock preserves that replacement instead of deleting it.

Interrupting after local deletion doesn’t restore the pairing; the command finishes successfully.

After removal, you can pair the client again.