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.

Resposta curta: 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.
Neste artigo
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, 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 --helplista as opções da versão instalada, e é a forma de resolver qualquer divergência com este texto. - Saiba a versão.
plesk versionmostra 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 [email protected]
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.-logine-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; consulteplesk bin customer --helppara 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
--infodepois 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
-passwdaparece no histórico do shell, empse em/proc/<pid>/cmdlinedurante a execução. Ler a senha de um arquivo 600 e repassá-la em-passwdnã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 ambientePSA_PASSWORDpara esse caso, com-passwd ''na linha de comando. Confirme o suporte com--helpna 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
--removeem 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.
Referências
- Documentação oficial (plesk) — Plesk CLI (Linux). Consultado em 2026-10-21.