# runner tokens

Gerencia tokens GitHub registrados nas apps. Tokens NUNCA são mostrados em plaintext — apenas fingerprints. Disponivel a partir da v2.13.0.

# Sintaxe

runner tokens list [--json]
runner tokens test <app> [--json]

E no runner add:

runner add --repo <r> --branch <b> --token-from <APP>

# `runner tokens list`

Enumera tokens registrados, agrupados por fingerprint. Apps que compartilham token aparecem juntas no mesmo grupo.

# Output humano

Tokens (2):
--------------------------------------------------------------------------------
  tk_a1b2…c3d4 | 3 app(s) | app1, app2, app3
  tk_e5f6…g7h8 | 1 app(s) | app4

# Output JSON

{
  "count": 2,
  "tokens": [
    {
      "fingerprint": "tk_a1b2…c3d4",
      "apps_count": 3,
      "apps": ["app1", "app2", "app3"]
    },
    {
      "fingerprint": "tk_e5f6…g7h8",
      "apps_count": 1,
      "apps": ["app4"]
    }
  ]
}

# Contrato de seguranca

• Tokens em plaintext nunca aparecem no output (qualquer formato)
• Apenas o fingerprint sha256 (12 chars hex, formato tk_4hex…4hex) eh exibido
• A lista eh derivada lendo cada state file e descriptografando localmente — sem trafego de rede

# `runner tokens test `

Valida o token de uma app via GitHub API (GET /user):

runner tokens test app1
# Token VALID for app1:
#   Fingerprint: tk_a1b2…c3d4
#   Username:    devborlot
#   Scopes:      repo, workflow

# Output JSON

{
  "valid": true,
  "app": "app1",
  "fingerprint": "tk_a1b2…c3d4",
  "username": "devborlot",
  "scopes": ["repo", "workflow"]
}

# Erros

# Como o teste funciona

1. Carrega state.github_token (encriptado)
2. Decrypt com mkey atual
3. Calcula fingerprint pra mostrar
4. Faz GET https://api.github.com/user com Authorization: Bearer <token>
5. Le x-oauth-scopes do response header

O token plaintext nao aparece em nenhum log/output.

# `runner add --token-from `

Reusa o token de outra app ja registrada. Util quando varias apps usam o mesmo token (ex: todas as repos da mesma org).

# Primeiro registro
runner add --repo devborlot/app1 --branch main --token ghp_xxx --ckey
# Reusing token from 'app1' (fingerprint: tk_a1b2…c3d4)

# Apps subsequentes — sem precisar do plaintext do token
runner add --repo devborlot/app2 --branch main --token-from app1
runner add --repo devborlot/app3 --branch main --token-from app1

# Comportamento

• Mutuamente exclusivo com --token (clap rejeita ambos)
• Decrypt local da mkey + re-encrypt pra nova app, plaintext nunca persiste fora do state file
• Fingerprint mostrado em stderr pra confirmacao visual
• Falha com token_source_not_found ou token_source_no_token se a app fonte nao existe ou nao tem token

# Erros

# Quando usar

# Veja Tambem

• runner add — registrar app
• runner edit — atualizar token de uma app existente
• Secrets e Encriptacao — duas-camadas (mkey + ckey)