Integração CLI

Gerencie contas SSH e Xray pela linha de comando. Copie os exemplos e veja as respostas JSON de cada comando.

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–z ou _. Nos demais, use A–Z, a–z, 0–9, _, - ou .. Não aceita espaços, acentos, ç, ; ou :. Exemplos válidos: Cliente_01, Maria.Silva e Joao-2. Use o login exato: Cliente_01 e cliente_01 sã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). Cada x é um dígito hexadecimal: 0–9, a–f ou A–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, ou null se a conta não tiver vencimento.
  • Limite: de 1 a 10.000 conexões, ou 0 para ilimitado. O retorno usa max_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.