Modalità CLI compatibile con l’AI ★Server

L’output di testo predefinito di lic non cambia e resta pienamente compatibile con le versioni precedenti: gli script esistenti non richiedono modifiche.

La modalità compatibile con l’AI si attiva con tre opzioni globali:

• --format=text|json|ndjson seleziona il formato del canale di output
• --quiet (alias -q) sopprime il banner del logo e termina subito con un errore davanti alle richieste interattive
• --strict-exit attiva i codici di uscita semantici

Quando è selezionato --format=json o --format=ndjson, stdout trasporta il flusso strutturato e i messaggi leggibili dalle persone vengono indirizzati su stderr, così i due canali non si mescolano mai.

Opzioni

—format <format>

Seleziona il formato di output usato su stdout. Valori ammessi:

lic MyApp.dll --keyfile keys.pem --sign --expiredate 365 --format json > result.json
lic MyApp.dll --keyfile keys.pem --sign --format ndjson | jq -c 'select(.level=="error")'

Con json o ndjson il banner del logo viene soppresso a prescindere da --logo, in modo che il primo byte su stdout sia JSON valido.

—quiet (-q)

Sopprime il banner del copyright e ogni richiesta interattiva. L’unica richiesta interattiva di lic è la password di un file di chiavi PFX: con --quiet, se manca --keypwd il comando termina con un errore esplicito invece di restare in attesa di input, e questo rende l’opzione sicura per le esecuzioni non presidiate sui runner di CI, nei container e da parte di agenti.

lic MyApp.dll --quiet --keyfile signing.pfx --keypwd "$KEY_PWD" --sign

--quiet è indipendente da --format: puoi combinarlo con l’output text per mantenere log leggibili dalle persone senza il banner.

—strict-exit

Attiva per il processo i codici di uscita semantici. Senza questa opzione, lic mantiene il contratto tradizionale, in cui 0 indica il successo e 1 qualsiasi errore.

I numeri sono gli stessi della tabella --strict-exit dell’offuscatore, quindi un solo chiamante può pilotare babel e lic con un’unica tabella dei codici di uscita; l’unica differenza è che il codice 30 indica qui l’elaborazione della licenza e lì l’offuscamento. La classificazione è riportata anche come exitReason nel risultato JSON, anche quando --strict-exit non è attivo.

lic MyApp.licenses --verify --keyfile keys.pem --strict-exit --quiet
echo "exit=$?"

Schema: lic.cli.v1

Tutti i payload strutturati contengono "schema": "lic.cli.v1" e un kind che indica di che documento si tratta: event, result, help o version. Lo schema ricalca babel.cli.v1 dell’offuscatore ma ha una versione separata, perché i due strumenti espongono insiemi di opzioni diversi. All’interno di una versione principale dello schema sono ammesse le modifiche additive; le modifiche incompatibili comportano un nuovo nome dello schema.

Record di evento

Ogni messaggio emesso mentre un’esecuzione è in corso viene associato a un evento:

{
  "schema":  "lic.cli.v1",
  "kind":    "event",
  "ts":      "2026-09-03T06:31:54.1686900Z",
  "level":   "info",
  "message": "License saved to 'MyApp.licenses'"
}

Envelope del risultato

—format=json

Al termine dell’esecuzione viene scritto su stdout un unico oggetto JSON. Contiene il riepilogo dell’esecuzione e tutti gli eventi accumulati nel buffer durante l’esecuzione:

{
  "schema":     "lic.cli.v1",
  "kind":       "result",
  "exitCode":   0,
  "exitReason": "success",
  "elapsedMs":  133,
  "warnings":   0,
  "errors":     0,
  "events": [
    { "schema": "lic.cli.v1", "kind": "event", "ts": "2026-09-03T06:31:54.1686900Z", "level": "info", "message": "License saved to 'MyApp.licenses'" }
  ]
}

Un’esecuzione non riuscita riporta la classe dell’errore in exitReason e l’errore tra gli eventi. Qui l’assembly di input non esisteva:

{
  "schema":     "lic.cli.v1",
  "kind":       "result",
  "exitCode":   20,
  "exitReason": "inputNotFound",
  "elapsedMs":  34,
  "warnings":   0,
  "errors":     1,
  "events": [
    { "schema": "lic.cli.v1", "kind": "event", "ts": "2026-09-03T06:30:27.4366510Z", "level": "error", "message": "Error: The specified file '/build/missing.dll' was not found." }
  ]
}

—format=ndjson

Ogni evento viene scritto non appena è prodotto, su una riga a sé. Dopo l’ultimo evento viene aggiunta una riga finale con il risultato, senza l’array events, perché gli eventi sono già stati trasmessi:

{"schema":"lic.cli.v1","kind":"event","ts":"2026-09-03T06:31:54.3357790Z","level":"info","message":"License saved to 'MyApp.licenses'"}
{"schema":"lic.cli.v1","kind":"result","exitCode":0,"exitReason":"success","elapsedMs":141,"warnings":0,"errors":0}

—help leggibile dalle macchine

lic --help --format=json emette una descrizione completa di ogni opzione pubblica, adatta agli strumenti che devono esaminare l’interfaccia della CLI: completamento automatico della shell, agenti AI, generatori di documentazione.

{
  "schema":  "lic.cli.v1",
  "kind":    "help",
  "version": "12.0.0.0",
  "usage":   "lic.exe <assembly|licensefile> [<other assemblies>...] [options]",
  "options": [
    {
      "name":        "trial",
      "aliases":     [],
      "description": "Add or update trial license restriction",
      "args":        "<key=value>",
      "argRequired": true,
      "argOptional": false,
      "negatable":   false,
      "incremental": false,
      "container":   "hash",
      "type":        "string",
      "group":       "- License Restrictions -",
      "details":     "Set trial restriction properties entering key-value pairs:\n\nid=<id>         Restriction id\nexpire=<date>   Set expiration date\ndays=<n>        Set number of trial days\n..."
    }
  ]
}

È supportata anche una forma limitata a una sola opzione: lic --help trial --format=json emette lo stesso envelope, che contiene solo l’opzione trial. Le opzioni nascoste e interne non vengono mai restituite.

—version leggibile dalle macchine

lic --version --format=json emette le informazioni su prodotto, versione, runtime e piattaforma:

{
  "schema":      "lic.cli.v1",
  "kind":        "version",
  "product":     "Babel Licensing",
  "version":     "12.0.0.0",
  "fileVersion": "12.0.0.1",
  "runtime":     ".NET 10.0.0",
  "platform":    "osx-arm64"
}

Il campo platform usa l’identificatore di runtime (RID) di .NET su .NET 5 e versioni successive, e una stringa sintetica <os>-<arch> sui target precedenti.

Pilotare lic da un agente

Un agente che non ha mai visto lic può usarlo partendo dalla sola guida in JSON: legge lo schema delle opzioni, costruisce la riga di comando in base alle indicazioni di args e container, la esegue con --format json --quiet --strict-exit e decide come proseguire in base a exitReason. Un ciclo tipico per emettere una licenza ha questo aspetto:

lic --help --format json > lic-options.json
lic MyApp.dll --keyfile keys.pem --sign --licensee name="Contoso" --expiredate 365 --output MyApp.licenses --format json --quiet --strict-exit > result.json
jq -r '.exitReason' result.json

Lo stesso contratto, gli stessi codici di uscita e gli stessi nomi delle opzioni valgono per la riga di comando dell’offuscatore, documentata in Modalità CLI compatibile con l’AI nel manuale dell’offuscatore, quindi una sola integrazione copre entrambi gli strumenti.

Compatibilità con le versioni precedenti

• Il valore predefinito di --format è text; l’output testuale tradizionale, i codici di uscita e il comportamento non cambiano se non specifichi nessuna delle nuove opzioni.
• Senza --strict-exit, il processo continua a restituire 0 in caso di successo e 1 per qualsiasi errore, quindi i controlli esistenti che decidono in base a $? continuano a funzionare.
• --quiet è indipendente e può essere attivato senza abilitare l’output strutturato.