# CLI

shikiphp include un piccolo strumento a riga di comando in `bin/shikiphp` (installato come `vendor/bin/shikiphp` nel progetto). Offre tre comandi: `highlight` visualizza un file in HTML, mentre `langs` e `themes` elencano il contenuto del bundle.

## `highlight`

Evidenzia un file in HTML e lo stampa su stdout.

```bash
vendor/bin/shikiphp highlight <file> [--lang=<lang>] [--theme=<theme>]
```

- `<file>` — il percorso da leggere. Deve essere un file esistente; non viene letto lo standard input.
- `--lang` — l’ID o alias del linguaggio. Se omesso, l’estensione del file viene usata così com’è come ID (in assenza di estensione, si ricorre a `txt`).
- `--theme` — l’ID del tema. Il valore predefinito è `github-dark`.

```bash
vendor/bin/shikiphp highlight src/App.php --lang=php --theme=nord
```

L’output è lo stesso blocco `<pre class="shiki …">` a tema singolo restituito da [`codeToHtml`](https://shikiphp.inline0.dev/it/docs/api#shikiphpcodetohtml), seguito da un a capo, quindi può essere reindirizzato direttamente a un file:

```bash
vendor/bin/shikiphp highlight src/App.php --theme=github-light > app.html
```

Il comando non accetta altre opzioni. Per temi chiaro e scuro, transformer o qualsiasi altra [opzione](https://shikiphp.inline0.dev/it/docs/options), usate invece l’PHP API.

### Opzioni e argomenti

Le opzioni devono usare la forma `--name=value`. Qualsiasi altro argomento che inizi con `--` viene ignorato; come file viene usato l’ultimo argomento che non inizia con `--`. Pertanto `--lang php file.rs` evidenzia `file.rs` come Rust: `--lang` viene ignorato, `php` viene sostituito da `file.rs` e il linguaggio è ricavato dall’estensione `.rs`.

### Rilevamento del linguaggio

Senza `--lang`, l'estensione diventa l'id della lingua senza modifiche. Funziona
quando l'estensione è già un id incluso o un alias: `php`, `js`, `ts`,
`tsx`, `py`, `rs`, `go`, `md`, `yml`, `json`, `sh` e molti altri (vedere
[Lingue](https://shikiphp.inline0.dev/it/docs/languages)). Non funziona per:

- file senza estensione, come `Makefile` o `Dockerfile`, per i quali si usa
  `txt`;
- estensioni che non sono un id di lingua, come `.txt`.

`txt` non è una lingua inclusa, quindi entrambi i casi si interrompono attualmente con un
errore `Unknown language "txt"` ([#3](https://github.com/inline0/shikiphp/issues/3)).
Passate `--lang` per questi file:

```bash
vendor/bin/shikiphp highlight Dockerfile --lang=docker
vendor/bin/shikiphp highlight Makefile --lang=make
```

## `langs`

Stampa ogni id accettato dal bundle come lingua, uno per riga.

```bash
vendor/bin/shikiphp langs
```

L'elenco contiene 350 righe: gli 253 id grammaticali inclusi nel bundle, nell'ordine del bundle (non
alfabetico), seguiti dai loro 97 alias (`js`, `cjs`, `mjs` e così via).
Gli id grammaticali includono 18 grammatiche ausiliarie incorporate da altre grammatiche, come
`vue-directives` e `es-tag-css`; vedere [Lingue](https://shikiphp.inline0.dev/it/docs/languages) per il
catalogo con nomi e alias. Passate l'elenco a `sort` per ordinarlo alfabeticamente.

## `themes`

Stampa ogni id dei temi inclusi nel bundle, uno per riga, in ordine alfabetico (65 temi).

```bash
vendor/bin/shikiphp themes
```

Vedere [Temi](https://shikiphp.inline0.dev/it/docs/themes) per il catalogo con nomi e tipi chiaro/scuro.

## Guida e codice di uscita

Eseguite senza un comando, oppure con `-h` / `--help` / `help`, per stampare le istruzioni.

```bash
vendor/bin/shikiphp --help
```

| Situazione | Output | Codice di uscita |
| --- | --- | --- |
| Operazione riuscita o guida | stdout | `0` |
| Comando sconosciuto | `Unknown command: <name>` su stderr | `1` |
| `highlight` senza file o file inesistente | riga delle istruzioni su stderr | `1` |
| Lingua o tema sconosciuto | `Shikiphp\Exceptions\Highlight` non gestito (errore fatale PHP con stack trace) | `255` |