- Criar conta SSH + Xray
- Criar conta temporária
- Substituir ou criar conta
- Consultar conta
- Listar contas
- Consultar se uma conta está online
- Listar online no servidor
- Remover conta
- Consultar pedido
- Consultar portas ativas
- Listar comandos
- Estados da fila
- Parâmetros
Antes de começar
Execute na VPS Linux como root, com o SSHCore atualizado e licença válida.
Criar, criar teste, substituir e excluir devolvem job_id quando o pedido entra na fila.
Pedido aceito não significa conta criada ou excluída. Cada conta tem um par exclusivo
de login SSH e UUID Xray. Se já houver uma alteração pendente ou em execução reservando esse par
(ou um dos seus dados), a CLI responde account_busy sem enfileirar outro pedido.
Cada chamada imprime um JSON no stdout. A saída é 0 no sucesso;
nos erros, use o código de saída e error.code. Os JSONs abaixo são formatados para leitura;
o programa emite uma única linha.
Criar conta SSH + Xray
sshcore-cli user create exemplo 'SenhaExemplo#2026' cd2a3204-6b3c-4f61-ac97-52fc05433d9d 30 2
Enfileira a criação de uma conta compartilhada. Ordem: login, senha, UUID, dias e limite. O login SSH e o UUID Xray formam um par fixo: se o par já estiver cadastrado ou um dos dados já estiver vinculado a outra conta, a CLI responde account_conflict sem enfileirar.
Sucesso · saída 0
{
"schema_version": 1,
"ok": true,
"data": {
"job_id": "e3664512-43ea-4621-9c17-76bd8fb875c5",
"operation": "create",
"login": "exemplo",
"state": "queued",
"queued_at": 1795046400
}
}
Erros
Saída 2 · invalid_argument
{
"schema_version": 1,
"ok": false,
"error": {
"code": "invalid_argument",
"message": "Argumentos inválidos; consulte help."
}
}
Saída 3 · permission_denied
{
"schema_version": 1,
"ok": false,
"error": {
"code": "permission_denied",
"message": "Execute localmente com privilégios de root."
}
}
Saída 5 · account_busy
{
"schema_version": 1,
"ok": false,
"error": {
"code": "account_busy",
"message": "Outra alteração de conta está em andamento."
}
}
Saída 6 · operation_failed
{
"schema_version": 1,
"ok": false,
"error": {
"code": "operation_failed",
"message": "Não foi possível concluir a operação; confira o estado antes de repetir."
}
}
Saída 8 · account_conflict
{
"schema_version": 1,
"ok": false,
"error": {
"code": "account_conflict",
"message": "O login ou o UUID já existe."
}
}
Criar conta temporária
sshcore-cli user test exemplo_teste 'SenhaTeste#2026' 96517308-933b-4023-9dcf-e31d52f98a5a 30 1
Enfileira uma conta temporária. Os 1 a 1.440 minutos começam quando a criação é executada. No Linux, a validade é de 2 dias; o cron remove a conta de teste vencida no próximo ciclo de um minuto.
Sucesso · saída 0
{
"schema_version": 1,
"ok": true,
"data": {
"job_id": "0af1e1de-ed8a-41e1-81f2-de3735ebda6b",
"operation": "test",
"login": "exemplo_teste",
"state": "queued",
"queued_at": 1795046400
}
}
Erros
Saída 2 · invalid_argument
{
"schema_version": 1,
"ok": false,
"error": {
"code": "invalid_argument",
"message": "Argumentos inválidos; consulte help."
}
}
Saída 3 · permission_denied
{
"schema_version": 1,
"ok": false,
"error": {
"code": "permission_denied",
"message": "Execute localmente com privilégios de root."
}
}
Saída 5 · account_busy
{
"schema_version": 1,
"ok": false,
"error": {
"code": "account_busy",
"message": "Outra alteração de conta está em andamento."
}
}
Saída 6 · operation_failed
{
"schema_version": 1,
"ok": false,
"error": {
"code": "operation_failed",
"message": "Não foi possível concluir a operação; confira o estado antes de repetir."
}
}
Saída 8 · account_conflict
{
"schema_version": 1,
"ok": false,
"error": {
"code": "account_conflict",
"message": "O login ou o UUID já existe."
}
}
Saída 11 · cleanup_unavailable
{
"schema_version": 1,
"ok": false,
"error": {
"code": "cleanup_unavailable",
"message": "O cron de remoção das contas de teste não está ativo."
}
}
Substituir ou criar conta
sshcore-cli user replace exemplo 'NovaSenha#2026' cd2a3204-6b3c-4f61-ac97-52fc05433d9d 30 2
Não consulta se o login existe no envio. Na execução, remove a conta existente e o UUID vinculado antes de criar a nova conta normal. Se o login não existir, cria direto. Encerra sessões da conta antiga e cancela o prazo se ela era de teste.
Sucesso · saída 0
{
"schema_version": 1,
"ok": true,
"data": {
"job_id": "f2764121-eeab-4f53-a861-e6a545b35cf2",
"operation": "replace",
"login": "exemplo",
"state": "queued",
"queued_at": 1795046400
}
}
Erros
Saída 2 · invalid_argument
{
"schema_version": 1,
"ok": false,
"error": {
"code": "invalid_argument",
"message": "Argumentos inválidos; consulte help."
}
}
Saída 3 · permission_denied
{
"schema_version": 1,
"ok": false,
"error": {
"code": "permission_denied",
"message": "Execute localmente com privilégios de root."
}
}
Saída 5 · account_busy
{
"schema_version": 1,
"ok": false,
"error": {
"code": "account_busy",
"message": "Outra alteração de conta está em andamento."
}
}
Saída 6 · operation_failed
{
"schema_version": 1,
"ok": false,
"error": {
"code": "operation_failed",
"message": "Não foi possível concluir a operação; confira o estado antes de repetir."
}
}
Consultar conta
sshcore-cli user get exemplo
Retorna a conta gerenciada, sem a senha.
Sucesso · saída 0
{
"schema_version": 1,
"ok": true,
"data": {
"login": "exemplo",
"uuid": "cd2a3204-6b3c-4f61-ac97-52fc05433d9d",
"expires_at": 1797724800,
"max_connections": 2
}
}
Erros
Saída 2 · invalid_argument
{
"schema_version": 1,
"ok": false,
"error": {
"code": "invalid_argument",
"message": "Argumentos inválidos; consulte help."
}
}
Saída 3 · permission_denied
{
"schema_version": 1,
"ok": false,
"error": {
"code": "permission_denied",
"message": "Execute localmente com privilégios de root."
}
}
Saída 4 · not_found
{
"schema_version": 1,
"ok": false,
"error": {
"code": "not_found",
"message": "Conta SSH/Xray gerenciada não encontrada."
}
}
Saída 6 · operation_failed
{
"schema_version": 1,
"ok": false,
"error": {
"code": "operation_failed",
"message": "Não foi possível concluir a operação; confira o estado antes de repetir."
}
}
Saída 7 · license_unavailable
{
"schema_version": 1,
"ok": false,
"error": {
"code": "license_unavailable",
"message": "Não foi possível validar a licença SSHCore."
}
}
Listar contas
sshcore-cli user list
Retorna as contas compartilhadas em ordem de login. Sem contas, users é uma lista vazia.
Sucesso · saída 0
{
"schema_version": 1,
"ok": true,
"data": {
"users": [
{
"login": "exemplo",
"uuid": "cd2a3204-6b3c-4f61-ac97-52fc05433d9d",
"expires_at": 1797724800,
"max_connections": 2
}
]
}
}
Erros
Saída 2 · invalid_argument
{
"schema_version": 1,
"ok": false,
"error": {
"code": "invalid_argument",
"message": "Argumentos inválidos; consulte help."
}
}
Saída 3 · permission_denied
{
"schema_version": 1,
"ok": false,
"error": {
"code": "permission_denied",
"message": "Execute localmente com privilégios de root."
}
}
Saída 6 · operation_failed
{
"schema_version": 1,
"ok": false,
"error": {
"code": "operation_failed",
"message": "Não foi possível concluir a operação; confira o estado antes de repetir."
}
}
Saída 7 · license_unavailable
{
"schema_version": 1,
"ok": false,
"error": {
"code": "license_unavailable",
"message": "Não foi possível validar a licença SSHCore."
}
}
Consultar se uma conta está online
sshcore-cli online exemplo
protocols indica ssh, xray ou os dois, conforme a atividade detectada. Se estiver offline, a lista vem vazia, online é false e as contagens são zero.
Sucesso · saída 0
{
"schema_version": 1,
"ok": true,
"data": {
"login": "exemplo",
"ssh_sessions": 1,
"xray_devices": 1,
"total": 2,
"online": true,
"protocols": [
"ssh",
"xray"
]
}
}
Erros
Saída 2 · invalid_argument
{
"schema_version": 1,
"ok": false,
"error": {
"code": "invalid_argument",
"message": "Argumentos inválidos; consulte help."
}
}
Saída 3 · permission_denied
{
"schema_version": 1,
"ok": false,
"error": {
"code": "permission_denied",
"message": "Execute localmente com privilégios de root."
}
}
Saída 4 · not_found
{
"schema_version": 1,
"ok": false,
"error": {
"code": "not_found",
"message": "Conta SSH/Xray gerenciada não encontrada."
}
}
Saída 6 · operation_failed
{
"schema_version": 1,
"ok": false,
"error": {
"code": "operation_failed",
"message": "Não foi possível concluir a operação; confira o estado antes de repetir."
}
}
Saída 7 · license_unavailable
{
"schema_version": 1,
"ok": false,
"error": {
"code": "license_unavailable",
"message": "Não foi possível validar a licença SSHCore."
}
}
Listar online no servidor
sshcore-cli online
Mostra os protocolos de cada conta e do servidor. SSH conta sessões; Xray conta dispositivos com atividade nos últimos 60 segundos. BHTTP sobre SSH ou Xray aparece pelo protocolo da conta, não como um protocolo separado.
Sucesso · saída 0
{
"schema_version": 1,
"ok": true,
"data": {
"ssh_sessions": 1,
"xray_devices": 1,
"total": 2,
"protocols": [
"ssh",
"xray"
],
"users": [
{
"login": "exemplo",
"ssh_sessions": 1,
"xray_devices": 1,
"total": 2,
"online": true,
"protocols": [
"ssh",
"xray"
]
}
]
}
}
Erros
Saída 2 · invalid_argument
{
"schema_version": 1,
"ok": false,
"error": {
"code": "invalid_argument",
"message": "Argumentos inválidos; consulte help."
}
}
Saída 3 · permission_denied
{
"schema_version": 1,
"ok": false,
"error": {
"code": "permission_denied",
"message": "Execute localmente com privilégios de root."
}
}
Saída 6 · operation_failed
{
"schema_version": 1,
"ok": false,
"error": {
"code": "operation_failed",
"message": "Não foi possível concluir a operação; confira o estado antes de repetir."
}
}
Saída 7 · license_unavailable
{
"schema_version": 1,
"ok": false,
"error": {
"code": "license_unavailable",
"message": "Não foi possível validar a licença SSHCore."
}
}
Remover conta
sshcore-cli user delete exemplo --yes
Enfileira a exclusão. Se o login não existir, responde not_found na hora. A confirmação --yes é obrigatória. Se for conta de teste, o cron é cancelado para essa conta quando a exclusão conclui; espere done antes de recriar com o mesmo login ou UUID.
Sucesso · saída 0
{
"schema_version": 1,
"ok": true,
"data": {
"job_id": "02a3fddb-e68c-4747-8fd8-b9b38bed41c6",
"operation": "delete",
"login": "exemplo",
"state": "queued",
"queued_at": 1795046400
}
}
Erros
Saída 2 · invalid_argument
{
"schema_version": 1,
"ok": false,
"error": {
"code": "invalid_argument",
"message": "Argumentos inválidos; consulte help."
}
}
Saída 3 · permission_denied
{
"schema_version": 1,
"ok": false,
"error": {
"code": "permission_denied",
"message": "Execute localmente com privilégios de root."
}
}
Saída 4 · not_found
{
"schema_version": 1,
"ok": false,
"error": {
"code": "not_found",
"message": "Conta SSH/Xray gerenciada não encontrada."
}
}
Saída 5 · account_busy
{
"schema_version": 1,
"ok": false,
"error": {
"code": "account_busy",
"message": "Outra alteração de conta está em andamento."
}
}
Saída 6 · operation_failed
{
"schema_version": 1,
"ok": false,
"error": {
"code": "operation_failed",
"message": "Não foi possível concluir a operação; confira o estado antes de repetir."
}
}
Consultar pedido
sshcore-cli job get e3664512-43ea-4621-9c17-76bd8fb875c5
Substitua o ID pelo job_id recebido. A consulta responde de imediato; não espera o pedido terminar.
Sucesso · saída 0
{
"schema_version": 1,
"ok": true,
"data": {
"job_id": "e3664512-43ea-4621-9c17-76bd8fb875c5",
"operation": "create",
"login": "exemplo",
"state": "queued",
"queued_at": 1795046400,
"started_at": null,
"finished_at": null
}
}
Erros
Saída 2 · invalid_argument
{
"schema_version": 1,
"ok": false,
"error": {
"code": "invalid_argument",
"message": "Argumentos inválidos; consulte help."
}
}
Saída 3 · permission_denied
{
"schema_version": 1,
"ok": false,
"error": {
"code": "permission_denied",
"message": "Execute localmente com privilégios de root."
}
}
Saída 4 · job_not_found
{
"schema_version": 1,
"ok": false,
"error": {
"code": "job_not_found",
"message": "Pedido não encontrado."
}
}
Saída 6 · operation_failed
{
"schema_version": 1,
"ok": false,
"error": {
"code": "operation_failed",
"message": "Não foi possível concluir a operação; confira o estado antes de repetir."
}
}
Consultar portas ativas
sshcore-cli status
Retorna as escutas reais, como em Portas ativas do menu principal. Não inclui serviços parados nem conexões de saída. A porta é a do socket local: por exemplo, DNSTT escuta na 5300/UDP; não é uma checagem de firewall ou redirecionamento da 53.
Sucesso · saída 0
{
"schema_version": 1,
"ok": true,
"data": {
"ports": [
{
"service": "DNSTT",
"port": 5300,
"transport": "udp"
},
{
"service": "NTProxy",
"port": 80,
"transport": "tcp"
},
{
"service": "OpenSSH",
"port": 22,
"transport": "tcp"
}
]
}
}
Erros
Saída 2 · invalid_argument
{
"schema_version": 1,
"ok": false,
"error": {
"code": "invalid_argument",
"message": "Argumentos inválidos; consulte help."
}
}
Saída 3 · permission_denied
{
"schema_version": 1,
"ok": false,
"error": {
"code": "permission_denied",
"message": "Execute localmente com privilégios de root."
}
}
Saída 6 · operation_failed
{
"schema_version": 1,
"ok": false,
"error": {
"code": "operation_failed",
"message": "Não foi possível concluir a operação; confira o estado antes de repetir."
}
}
Saída 7 · license_unavailable
{
"schema_version": 1,
"ok": false,
"error": {
"code": "license_unavailable",
"message": "Não foi possível validar a licença SSHCore."
}
}
Listar comandos
sshcore-cli help
Não exige root ou licença.
Sucesso · saída 0
{
"schema_version": 1,
"ok": true,
"data": {
"commands": [
"status",
"online [LOGIN]",
"user list",
"user get LOGIN",
"user create LOGIN SENHA UUID DAYS LIMIT",
"user test LOGIN SENHA UUID MINUTOS LIMIT",
"user replace LOGIN SENHA UUID DAYS LIMIT",
"user delete LOGIN --yes",
"job get ID"
]
}
}
Erros
Saída 2 · invalid_argument
{
"schema_version": 1,
"ok": false,
"error": {
"code": "invalid_argument",
"message": "Argumentos inválidos; consulte help."
}
}
Estados do pedido
queued: aguardando. running: executando. done: concluído, com data.result.
error: não concluído, com data.error. Uma consulta feita com sucesso sai com código 0 mesmo quando
o pedido terminou em erro. Nesse caso, o erro da operação está em data.error.exit_code e data.error.code.
Criação concluída
{
"schema_version": 1,
"ok": true,
"data": {
"job_id": "e3664512-43ea-4621-9c17-76bd8fb875c5",
"operation": "create",
"login": "exemplo",
"state": "done",
"queued_at": 1795046400,
"started_at": 1795046401,
"finished_at": 1795046402,
"result": {
"login": "exemplo",
"uuid": "cd2a3204-6b3c-4f61-ac97-52fc05433d9d",
"expires_at": 1797724800,
"max_connections": 2
}
}
}
Conta de teste concluída também retorna temporary: true e linux_expires_on (AAAA-MM-DD).
Na exclusão concluída, result contém login e deleted: true.
Substituição concluída
{
"schema_version": 1,
"ok": true,
"data": {
"job_id": "f2764121-eeab-4f53-a861-e6a545b35cf2",
"operation": "replace",
"login": "exemplo",
"state": "done",
"queued_at": 1795046400,
"started_at": 1795046401,
"finished_at": 1795046402,
"result": {
"login": "exemplo",
"uuid": "cd2a3204-6b3c-4f61-ac97-52fc05433d9d",
"expires_at": 1797724800,
"max_connections": 2,
"replaced": true
}
}
}
result.replaced é true se havia conta anterior e false
se foi uma criação direta. O comando não remove outro cadastro para liberar um UUID. Se excluir a conta anterior
mas falhar ao criar a nova, devolve replace_create_failed; confira a conta antes de reenviar.
Erro durante a execução
{
"schema_version": 1,
"ok": true,
"data": {
"job_id": "e3664512-43ea-4621-9c17-76bd8fb875c5",
"operation": "create",
"login": "exemplo",
"state": "error",
"queued_at": 1795046400,
"started_at": 1795046401,
"finished_at": 1795046402,
"error": {
"exit_code": 7,
"code": "license_unavailable",
"message": "Não foi possível validar a licença SSHCore."
}
}
}
not_found · erro da operação
{
"exit_code": 4,
"code": "not_found",
"message": "Conta SSH/Xray gerenciada não encontrada."
}
account_busy · erro da operação
{
"exit_code": 5,
"code": "account_busy",
"message": "Outra alteração de conta está em andamento."
}
operation_failed · erro da operação
{
"exit_code": 6,
"code": "operation_failed",
"message": "Não foi possível concluir a operação; confira o estado antes de repetir."
}
license_unavailable · erro da operação
{
"exit_code": 7,
"code": "license_unavailable",
"message": "Não foi possível validar a licença SSHCore."
}
account_conflict · erro da operação
{
"exit_code": 8,
"code": "account_conflict",
"message": "O login ou o UUID já existe."
}
cleanup_unavailable · erro da operação
{
"exit_code": 11,
"code": "cleanup_unavailable",
"message": "O cron de remoção das contas de teste não está ativo."
}
interrupted · erro da operação
{
"exit_code": 12,
"code": "interrupted",
"message": "A execução foi interrompida. Confira a conta antes de reenviar."
}
account_changed · erro da operação
{
"exit_code": 13,
"code": "account_changed",
"message": "A conta mudou desde o envio do pedido; nada foi excluído."
}
replace_create_failed · erro da operação
{
"exit_code": 14,
"code": "replace_create_failed",
"message": "A conta anterior foi excluída, mas a nova não foi criada com sucesso. Confira o estado antes de reenviar."
}
O serviço sshcore-cli-worker.service processa um pedido por vez em ordem de entrada.
Se o serviço parar, os pedidos aguardando ficam no SQLite. Se parar durante uma operação, o pedido recebe
interrupted quando o serviço voltar: confira a conta antes de enviar novamente. A licença é checada ao executar.
Parâmetros e campos
- Login (1 a 32 caracteres): no primeiro caractere, use
A–Z,a–zou_. Nos demais, useA–Z,a–z,0–9,_,-ou.. Não aceita espaços, acentos,ç,;ou:. Exemplos válidos:Cliente_01,Maria.SilvaeJoao-2. Use o login exato:Cliente_01ecliente_01são nomes diferentes. - Senha: UTF-8, até 1.024 bytes, sem controles, dois-pontos ou espaços nas pontas. Nunca aparece no JSON; pode aparecer na lista de processos enquanto a CLI roda. Não registre o comando completo em logs.
- UUID: 36 caracteres no formato
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx(grupos de 8–4–4–4–12, com hífens). Cadaxé um dígito hexadecimal:0–9,a–fouA–F. Exemplo:cd2a3204-6b3c-4f61-ac97-52fc05433d9d. Não aceita espaços, chaves, ausência de hífens nem o UUID todo zerado. Deve ser exclusivo e sai no JSON em minúsculas. Trate-o como credencial. - Dias: de 1 a 1.825 (5 anos de 365 dias). Conta de teste usa minutos, de 1 a 1.440.
expires_até o vencimento em segundos Unix, ounullse a conta não tiver vencimento. - Limite: de 1 a 10.000 conexões, ou
0para ilimitado. O retorno usamax_connections.
Use credenciais próprias em vez dos valores de exemplo. Se não houver JSON, trate como falha de execução. Não exponha este comando administrativo diretamente a um endpoint público.