> ## Documentation Index
> Fetch the complete documentation index at: https://frp.xdr.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# frpctl Guide

> Use the primary operator CLI for clients, services, enrollment, diagnostics, and lifecycle operations.

# frpctl Guide

`frpctl` is the everyday operator interface. You can use it interactively or run a full command directly from the shell.

## Start here if you are new

```bash theme={null}
sudo frpctl
```

The interactive CLI provides completion and context help:

```text theme={null}
Tab    show/complete valid next tokens
?      context-sensitive help
help   full command help
↑/↓    in-memory history for this session
menu   guided numbered interface
exit   leave the CLI
```

## Choose the command by what you want to do

| Intent                           | Start with                                     |
| -------------------------------- | ---------------------------------------------- |
| Is everything healthy?           | `show status`, `doctor`                        |
| What clients exist?              | `show clients`                                 |
| Inspect one client               | `show client <ID>`                             |
| Onboard a new client             | `create zero-touch`                            |
| Create a manual Enrollment Code  | `create enrollment`                            |
| See a client's services          | `show client <ID> services`                    |
| Change a client's label/note/tag | `set client <ID> ...`                          |
| Add/edit a client-side service   | `add service`, `set service ...`, then `apply` |
| Temporarily stop a service       | `disable service <service-id>`                 |
| Permanently free a service port  | `release service <ID> <service-id>`            |
| Block client management identity | `revoke client <ID>`                           |
| Check for project update         | `update project --check`                       |
| Create a backup                  | `create backup`                                |

## The grammar

```text theme={null}
<verb> <resource> [target] [property] [value]
```

```mermaid theme={null}
flowchart LR
    V[Verb\nshow / set / create / release] --> R[Resource\nclient / service / enrollment]
    R --> T[Target\nCLIENT ID / Service ID]
    T --> P[Optional property/value]
```

## CLIENT ID is the canonical selector

The server's canonical identity is the immutable **CLIENT ID**. Label and hostname are human-friendly metadata and can change.

`show clients` prints CLIENT ID first. Tab completion prefers CLIENT ID. A unique label or hostname may work when typed manually, but an ambiguous selector fails closed.

## Common server commands

```text theme={null}
show status
show version
show clients
show client <ID>
show client <ID> services
show client <ID> tags
show enrollments
show audit
show upstream

create zero-touch
create enrollment
create enrollment --one-line --ssh --ssh-user aella --label branch-a
create enrollments --count 3
create backup

set client <ID> label <value>
set client <ID> note <value>
set client <ID> tag <key> <value>
set server hostname <fqdn>

unset client <ID> label
unset client <ID> note
unset client <ID> tag <key>
unset server hostname

revoke enrollment <ID>
revoke client <ID>
release service <ID> <service-id>
release client <ID>

update project --check
update project
update frp --check
doctor
```

## Common client commands

```text theme={null}
show status
show version
show services
show info

add service
set service <service-id> target-host <host>
set service <service-id> target-port <port>
set service <service-id> ssh-user <user>
set service <service-id> name <value>

enable service <service-id>
disable service <service-id>
apply
discard

doctor
```

Client service changes are staged. `apply` makes them live; `discard` drops pending changes.

## Three lifecycle verbs you must not mix up

```mermaid theme={null}
flowchart TD
    A[Need to stop publication?] -->|temporary| D[disable]
    A -->|permanently free port| R[release]
    B[Need to block management identity?] --> V[revoke]
```

```text theme={null}
disable != release
revoke  != release
```

## Stable vs development commands

This documentation's operational baseline is stable **v2.1.2**. The `main` branch identifies as 2.1.3 development and may contain additional commands or lifecycle helpers not present in the stable tag.

For exact stable syntax, use the [CLI Reference](/frpctl/cli-reference).

## Safety behavior

* `doctor` is read-only.
* `history` is session-only and is not persisted by `frpctl`.
* FRP stays pinned to the project-tested version; `show upstream` is informational.
* Ambiguous identity selection should fail rather than guess.