# Plesk CLI: criar e suspender assinatura no terminal

Criar, consultar, suspender e reativar assinaturas pelo terminal, com a verificação de cada passo e o que fazer quando o utilitário devolve erro.

> Use plesk bin subscription --create para criar a assinatura (com -owner, -service-plan, -ip, -login e -passwd), --webspace-off para suspender e --webspace-on para reativar. Confirme cada passo com --info e com o código de saída, que é 0 no sucesso.

João Rizzon · 2026-11-12 · Painéis

---

## Antes de usar, confirme a versão e o help local

Todo o gerenciamento de assinaturas do Plesk em Linux passa por `plesk bin`, que chama os utilitários de linha de comando do painel. O que interessa aqui é `plesk bin subscription`, com apoio de `customer` e `service_plan`. A referência é a [documentação oficial do Plesk CLI para Linux](https://docs.plesk.com/en-US/onyx/cli-linux_sitemap.xml), na versão Onyx. Versões posteriores mantêm a maior parte das opções, mas confira no servidor antes de colocar algo em produção.

Duas condições valem para tudo o que segue:

- **A ajuda local é a fonte mais confiável.** `plesk bin subscription --help` lista as opções da versão instalada, e é a forma de resolver qualquer divergência com este texto.
- **Saiba a versão.** `plesk version` mostra a versão e o sistema. Opções novas não existem em instalações antigas.

```
plesk version
plesk bin subscription --help | less
```

O utilitário não depende da interface web. Se o `sw-cp-server` ou o nginx do painel estiver parado, os comandos continuam funcionando, desde que o banco esteja no ar. Aqui fica só o caminho de terminal.

## Inventário antes de mexer

Criar ou suspender sem saber o que existe é a origem dos erros mais comuns: plano com nome digitado errado, dono inexistente, domínio já cadastrado. Faça o inventário primeiro.

```
# assinaturas existentes
plesk bin subscription --list

# planos de serviço disponíveis
plesk bin service_plan --list

# detalhes de uma assinatura: dono, plano, IP, status
plesk bin subscription --info example.com
```

`--info` é o comando que você vai repetir depois de cada alteração para confirmar o estado. Guarde a saída antes da mudança: ela é o seu ponto de reversão documentado.

```
plesk bin subscription --info example.com > /root/antes-example.com.txt
```

O nome passado em `-service-plan` precisa bater exatamente com o que `service_plan --list` devolve.

## Criar uma assinatura

Uma assinatura no Plesk é um domínio principal com espaço de hospedagem, um usuário de sistema, um IP e, opcionalmente, um plano de serviço e um cliente dono. A ordem é: dono existe, plano existe, cria a assinatura.

### Passo 1: criar o cliente, se ainda não existir

Se a assinatura vai pertencer ao administrador, pule este passo e use `-owner admin`.

```
read -rs PSA_PASSWORD && export PSA_PASSWORD
plesk bin customer --create cliente01 -name "Cliente Exemplo" -passwd '' -email contato@example.com
unset PSA_PASSWORD
```

O login (`cliente01`) é o identificador que você usará em `-owner`. Dados acima são fictícios, apenas exemplo. A senha entra pela variável `PSA_PASSWORD` com `-passwd ''`, lida por `read -rs`, para não aparecer em argv, em `ps` nem no histórico do shell (detalhes em Colocando em script). Confirme com `--help` que a sua versão suporta a variável.

### Passo 2: criar a assinatura

```
read -rs PSA_PASSWORD && export PSA_PASSWORD
plesk bin subscription --create example.com \
  -owner cliente01 \
  -service-plan "Default Domain" \
  -ip 192.0.2.10 \
  -login exuser \
  -passwd ''; rc=$?
unset PSA_PASSWORD
```

O que cada opção faz, conforme a documentação:

- `-owner`: login do cliente ou revendedor dono. Sem ela, o dono é o administrador.
- `-service-plan`: plano que define limites e permissões. A assinatura fica vinculada a ele.
- `-ip`: endereço que precisa já estar cadastrado no painel. Um IP que existe na interface de rede mas não foi registrado no Plesk gera erro. Se o dono é um revendedor, o IP também precisa estar no pool de IPs atribuído a ele.
- `-login` e `-passwd`: usuário de sistema (FTP/SSH) da assinatura. O login precisa ser único no servidor.

### Passo 3: conferir

Na execução bem-sucedida, o utilitário imprime uma linha iniciada por `SUCCESS:` e sai com código 0. Esse código foi guardado em `rc` no Passo 2, logo após o `--create`. Um `echo $?` depois do `unset PSA_PASSWORD` mostraria o código do `unset`, que é sempre 0, e não o da criação. Não confie só na mensagem: rode `--info` e verifique dono, plano e IP.

```
echo $rc
plesk bin subscription --info example.com
```

Para desfazer uma criação errada, `plesk bin subscription --remove example.com`. Isso apaga os arquivos do site também. Numa assinatura recém-criada não há o que perder; numa antiga, faça backup antes.

## Suspender e reativar

Suspensão desativa o espaço de hospedagem sem apagar dados. É a operação que mais aparece em automação de cobrança.

```
# suspender
plesk bin subscription --webspace-off example.com

# reativar
plesk bin subscription --webspace-on example.com
```

Pontos sobre o alcance da suspensão. O efeito exato sobre site, entrega de e-mail, FTP/SSH e DNS não foi medido para este texto: antes de automatizar, suspenda uma assinatura de teste e confira com `curl -I`, um envio de e-mail e uma tentativa de login FTP o que a sua versão faz.

- A suspensão é da assinatura. Se o cliente tem várias, suspender uma não mexe nas outras. Para suspender todas de uma vez, o caminho é agir sobre o cliente com `plesk bin customer`; consulte `plesk bin customer --help` para as opções da sua versão.
- Suspensão não é exclusão. Arquivos, bancos e caixas de e-mail continuam no disco e voltam com `--webspace-on`.
- Confirme o status em `--info` depois de cada operação. Em script, isso é o que diferencia "o comando rodou" de "a assinatura está no estado esperado".

| Operação | Comando | Reversão | Perde dados |
|---|---|---|---||
| Listar | `subscription --list` | não se aplica | não |
| Consultar | `subscription --info <dominio>` | não se aplica | não |
| Criar | `subscription --create <dominio> ...` | `subscription --remove <dominio>` | não |
| Suspender | `subscription --webspace-off <dominio>` | `subscription --webspace-on <dominio>` | não |
| Remover | `subscription --remove <dominio>` | só restaurando backup | sim |

## Quando o comando falha

A descrição do erro sai no terminal e costuma dizer exatamente o que faltou. Os casos abaixo são os que decorrem diretamente dos requisitos documentados de cada opção.

| Sintoma | Causa provável | O que fazer |
|---|---|---||
| Erro citando o plano | nome em `-service-plan` diferente do cadastrado | copie o nome de `service_plan --list`, com aspas |
| Erro citando o dono | login em `-owner` inexistente | `plesk bin customer --list` e crie o cliente antes |
| Erro citando o IP | IP não registrado no painel | registre o IP no Plesk antes de usar |
| Domínio ou login já existe | criação repetida ou login de sistema em uso | `subscription --info` para ver o que existe; troque o `-login` |
| Comando não encontrado | PATH sem `/usr/sbin` ou Plesk não instalado | chame `/usr/sbin/plesk` pelo caminho absoluto e confirme a instalação |
| Permissão negada | execução sem root | os utilitários de `plesk bin` exigem root; em automação com usuário não root, use `sudo` com regra restrita por operação (veja a regra de sudoers logo abaixo da tabela) em vez de liberar sudo amplo |
| Falha sem mensagem clara | banco ou serviço interno com problema | leia `/var/log/plesk/panel.log` |

Sobre a regra de sudo: no sudoers, um comando listado com argumentos só casa com exatamente esses argumentos. Uma regra com `/usr/sbin/plesk bin subscription` e nada mais bloqueia `--create example.com ...`. É preciso curinga explícito, de preferência um por operação. Edite com `visudo -f /etc/sudoers.d/plesk-automacao`:

```
Defaults:automacao env_keep += "PSA_PASSWORD"
automacao ALL=(root) NOPASSWD: /usr/sbin/plesk bin subscription --info *, \
  /usr/sbin/plesk bin subscription --webspace-off *, \
  /usr/sbin/plesk bin subscription --webspace-on *, \
  /usr/sbin/plesk bin subscription --create *
```

O risco do curinga: no sudoers, `*` também casa com espaços, então `--webspace-off *` aceita qualquer sequência de argumentos depois da opção, não só um domínio. Uma regra genérica `/usr/sbin/plesk bin subscription *` liberaria também `--remove`, que apaga dados. Liste só as operações que o script usa e deixe `--remove` fora da regra.

O `env_reset`, ativo por padrão, descarta `PSA_PASSWORD` ao passar pelo sudo, e o `--create` com `-passwd ''` falha ou fica sem a senha. A linha `Defaults:automacao env_keep += "PSA_PASSWORD"` acima mantém a variável. A alternativa é `sudo --preserve-env=PSA_PASSWORD /usr/sbin/plesk bin subscription --create ...`, que o sudo só aceita se a regra tiver a tag `SETENV` ou a variável estiver em `env_keep`. Valide a sintaxe com `visudo -c` e confira o que o usuário pode rodar com `sudo -l -U automacao`.

Não encontramos garantia documentada de que toda ação da CLI seja registrada em `panel.log`. Verifique no seu servidor: rode uma operação conhecida, como um `--info`, e procure por ela no log. Se aparecer, ele é o segundo lugar para olhar quando a saída do comando não explica a falha.

```
tail -n 50 /var/log/plesk/panel.log
```

Se a falha veio no meio de uma criação, rode `--info` antes de tentar de novo. Uma assinatura criada pela metade faz a segunda tentativa falhar com "já existe", e o correto é remover e recriar, não insistir.

## Colocando em script

Em automação, trate cada chamada como algo que pode falhar. O exemplo abaixo suspende uma lista de domínios lida de arquivo, registra o resultado e não para no primeiro erro, para que um domínio problemático não deixe os outros sem processar. Ele decide OK ou FALHA só pelo código de saída. A saída de `--info` de cada domínio vai para o log, mas o script não interpreta o campo de status, cujo texto pode variar entre versões: confira o log ou adapte um `grep` ao que a sua versão imprime.

```
#!/bin/bash
# exemplo: suspende os domínios listados em /root/suspender.txt (um por linha)
LOG=/root/suspensao-$(date +%F).log

while read -r dom; do
  [ -z "$dom" ] && continue
  if plesk bin subscription --webspace-off "$dom" >>"$LOG" 2>&1; then
    echo "OK $dom" >>"$LOG"
    plesk bin subscription --info "$dom" >>"$LOG" 2>&1
  else
    echo "FALHA $dom (codigo $?)" >>"$LOG"
  fi
done < /root/suspender.txt

grep -c '^FALHA' "$LOG"
```

Dois cuidados que evitam dor de cabeça:

- **Senhas fora de argv.** Senha passada em `-passwd` aparece no histórico do shell, em `ps` e em `/proc/<pid>/cmdline` durante a execução. Ler a senha de um arquivo 600 e repassá-la em `-passwd` não resolve: ela volta para argv e fica visível a qualquer usuário do servidor. A documentação da CLI do Plesk descreve a variável de ambiente `PSA_PASSWORD` para esse caso, com `-passwd ''` na linha de comando. Confirme o suporte com `--help` na sua versão antes de depender disso. O ambiente do processo (`/proc/<pid>/environ`) só é legível pelo dono do processo e por root, ao contrário de argv.
- **Teste com um domínio antes da lista.** A reversão de suspensão é simples, a de remoção não é. Nunca coloque `--remove` em laço sem revisar a lista.

## Quando a interface web não abre, o que a CLI ainda resolve

A CLI resolve a tarefa urgente, mas não o problema da interface. Duas coisas ajudam a separar as duas frentes.

Primeiro, `plesk login` gera um link de acesso único para o administrador. Se o link abre, o problema era de credencial ou sessão, não de serviço. Se não abre, a falha provavelmente está na camada web do painel ou no acesso de rede até ela, não necessariamente com o painel fora do ar. Confira nesta ordem: `systemctl status sw-cp-server` (e o nginx do painel), a porta 8443 escutando (`ss -ltnp | grep 8443`) e liberada no firewall com teste de conexão feito de fora do servidor, a validade do certificado do painel e se o hostname usado no link resolve para o IP correto.

Segundo, a CLI funcionar enquanto a tela não abre é em si um diagnóstico: banco e utilitários estão saudáveis, e a falha provavelmente está na camada web do painel ou no caminho de rede até ela (firewall na 8443, DNS do hostname, certificado). Isso estreita bastante a busca.

Enquanto isso, as operações de assinatura do dia a dia (consultar, criar, suspender, reativar) podem seguir pelo terminal sem depender de nada além do acesso root ao servidor.

