---
title: Panoramica CLI
description: >-
  Visualizza i documenti in locale, valida la configurazione, verifica i link non funzionanti e migra piattaforme con la CLI open-source di Jamdesk.
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://jamdesk.com/docs/llms.txt). Append `.md` to any page URL for its markdown version.

La CLI di Jamdesk consente di visualizzare i documenti in locale, validare la configurazione, verificare i link non funzionanti e migrare da altre piattaforme. È open-source con licenza [Apache License 2.0](https://github.com/jamdesk/jamdesk-cli).

## Installazione

### npm (Consigliato)

Installa globalmente da [npm](https://www.npmjs.com/package/jamdesk) per usare `jamdesk` da qualsiasi posizione:

```bash
npm install -g jamdesk
```

### Homebrew (macOS/Linux)

Installa tramite Homebrew su macOS o Linux:

```bash
brew tap jamdesk/tap
brew install jamdesk
```

### curl (macOS/Linux)

Installa tramite script:

```bash
curl -fsSL https://get.jamdesk.com | bash
```

Esegui l'upgrade o la disinstallazione:

```bash
curl -fsSL https://get.jamdesk.com/upgrade | bash
curl -fsSL https://get.jamdesk.com/uninstall | bash
```

### PowerShell (Windows)

Installa tramite script:

```powershell
iwr https://get.jamdesk.com/win | iex
```

Esegui l'upgrade o la disinstallazione:

```powershell
iwr https://get.jamdesk.com/upgrade | iex
iwr https://get.jamdesk.com/uninstall | iex
```

### npx

Esegui senza installare:

```bash
npx jamdesk dev
```

Dopo l'installazione, verifica che funzioni:

```bash
jamdesk --version
```

### Requisiti

- **Node.js** v20.0.0 o versione successiva
- **npm** v8 o versione successiva (consigliato)

## Avvio rapido

### 1. Crea un progetto

Crea un nuovo progetto di documentazione:

```bash
jamdesk init my-docs
cd my-docs
```

### 2. Avvia il server di sviluppo

Avvia il server di sviluppo locale con ricaricamento automatico:

```bash
jamdesk dev
```

I documenti saranno disponibili all'indirizzo **http://localhost:3000/docs**

### 3. Valida prima del deploy

Verifica la presenza di errori di configurazione, link non funzionanti ed errori ortografici:

```bash
jamdesk validate
jamdesk broken-links
jamdesk fix --dry-run
jamdesk fix
jamdesk spellcheck
```

## Comandi

Esegui `jamdesk <command> --help` per informazioni dettagliate su qualsiasi comando.

### Sviluppo

#### jamdesk dev

Avvia il server di sviluppo locale con ricaricamento automatico.

```bash
jamdesk dev
jamdesk dev --port 3001
```

**Funzionalità:**

- Validazione automatica all'avvio (schema di docs.json, sintassi MDX e specifiche OpenAPI referenziate; una specifica non valida arresta il server, così puoi correggerla prima del deploy)
- Ricaricamento automatico quando cambiano i file MDX
- Ricostruzione automatica della navigazione quando cambia docs.json
- Ricaricamento del CSS personalizzato (`style.css`) al refresh del browser
- Funzionalità di ricerca completa
- Tutti i temi e i componenti disponibili

**Opzioni:**

| Flag | Descrizione |
|------|-------------|
| `-p, --port <port>` | Porta su cui eseguire il server (predefinita: 3000) |
| `-v, --verbose` | Abilita l'output dettagliato |

#### jamdesk init

Crea un nuovo progetto di documentazione.

```bash
jamdesk init              # Interactive mode
jamdesk init my-docs      # Create in new directory
```

Crea un nuovo progetto con:

- File di configurazione `docs.json`
- Pagine MDX di esempio
- Struttura di cartelle consigliata

### Autenticazione

#### jamdesk login

Accedi a Jamdesk tramite il browser. È obbligatorio prima del deploy.

```bash
jamdesk login
```

Apre la dashboard di Jamdesk nel browser per l'autenticazione. Le credenziali vengono salvate localmente in `~/.jamdeskrc`.

<Card title="Guida all'autenticazione" icon="key" href="/it/cli/authentication">
  Flusso di autenticazione tramite browser, gestione delle sessioni e risoluzione dei problemi
</Card>

#### jamdesk logout

Cancella le credenziali salvate.

```bash
jamdesk logout
```

#### jamdesk whoami

Mostra l'utente autenticato corrente e verifica che la sessione sia valida.

```bash
jamdesk whoami
```

### Validazione

#### jamdesk validate

Valida la configurazione `docs.json`, la sintassi MDX e le specifiche OpenAPI.

```bash
jamdesk validate
jamdesk validate --skip-mdx
```

**Verifica:**

- Sintassi JSON valida in docs.json
- Campi obbligatori (name, navigation)
- Valori dei temi validi
- Errori di sintassi MDX (ad esempio caratteri `<` non sottoposti a escape)
- Validazione delle specifiche OpenAPI (se configurata)
- Conformità allo schema

**Opzioni:**

| Flag | Descrizione |
|------|-------------|
| `--skip-mdx` | Ignora la validazione della sintassi MDX |
| `-v, --verbose` | Mostra un output dettagliato della validazione |

Esegui questo comando prima del deploy per rilevare tempestivamente gli errori.

#### jamdesk broken-links

Cerca link interni non funzionanti nella documentazione.

```bash
jamdesk broken-links
```

**Output di esempio:**

```text
docs/getting-started.mdx:15 - /docs/quikstart
  Did you mean: /docs/quickstart

Found 1 broken link in 45 files.
```

Rileva i link a pagine mancanti e gli errori di battitura. Consulta [Link e navigazione](https://jamdesk.com/docs/it/content/links#come-vengono-rilevati-i-link-interni) per maggiori dettagli.

#### jamdesk fix

Corregge automaticamente gli avvisi relativi a link interni non funzionanti quando la destinazione non è ambigua. Gestisce due categorie:

- **Anchor con errori di battitura**: un frammento come `#instalation` che dovrebbe chiaramente essere `#installation`
- **Deriva degli anchor tra lingue**: una pagina tradotta ha rinominato i titoli, ma i link in quella lingua puntano ancora al vecchio frammento inglese

```bash
# Preview what would change without touching any files
jamdesk fix --dry-run

# Apply fixes (prompts for confirmation)
jamdesk fix
```

**Output di esempio dell'esecuzione a secco:**

```text
Planned fixes:

  fr/ai/overview.mdx:9
    /fr/ai/selectors#ai-strategies  →  /fr/ai/selectors#stratégies-ia

(dry run — no files written)
```

Una correzione viene scritta solo quando l'anchor corretto rimanda a un titolo esistente nella pagina di destinazione. I casi ambigui vengono lasciati alla revisione manuale.

**Opzioni:**

| Flag | Descrizione |
|------|-------------|
| `--dry-run` | Visualizza le correzioni previste senza scrivere file |
| `-y, --yes` | Applica le correzioni senza chiedere conferma |
| `--types <list>` | Tipi di avviso separati da virgole da correggere (predefinito: tutti quelli supportati) |

<Card title="Guida alla correzione dei link" icon="wrench" href="/it/cli/fix-broken-links">
  Procedura dettagliata per visualizzare in anteprima, applicare, controllare e salvare le correzioni
</Card>

#### jamdesk spellcheck

Verifica la presenza di errori ortografici nella documentazione.

```bash
jamdesk spellcheck
```

**Output di esempio:**

```text
getting-started.mdx:14 - "recieve"
  └─ Did you mean: receive

Found 3 misspellings across 24 pages.
Tip: Run "jamdesk spellcheck --fix" to interactively fix or ignore words.
```

Usa un dizionario inglese con oltre 150 termini tecnici integrati (API, GraphQL, Kubernetes, React ecc.) per evitare che il gergo comune venga segnalato. Ignora blocchi di codice, codice inline, frontmatter, JSX, URL e percorsi di file. Attualmente supporta solo l'inglese; è previsto il supporto per dizionari multilingue.

**Opzioni:**

| Flag | Descrizione |
|------|-------------|
| `--fix` | Corregge interattivamente gli errori ortografici o li aggiunge all'elenco di esclusione |
| `--json` | Restituisce l'output in formato JSON (per le pipeline CI) |
| `-v, --verbose` | Mostra ogni file durante la verifica |

**La modalità di correzione interattiva (`--fix`)** esamina ogni parola errata distinta:

```text
1/10  "recieve" — found in 3 files
      intro.mdx:14, setup.mdx:7, guide.mdx:22

? What do you want to do?
❯ Fix → receive (recommended)
  Fix → relieve
  Ignore in the future (add to docs.json)
  Skip
```

- **Fix** sostituisce la parola con un suggerimento in tutti i file (in modo sicuro per la prosa, senza modificare blocchi di codice o attributi JSX). Vengono mostrati fino a 3 suggerimenti; la corrispondenza migliore è contrassegnata come consigliata.
- **Ignore** aggiunge la parola a `spellcheck.ignore` in docs.json, così non verrà più segnalata
- **Skip** non esegue alcuna azione durante questa esecuzione

Le modifiche vengono visualizzate in anteprima e richiedono conferma prima dell'applicazione.

**Elenco di esclusione personalizzato:** aggiungi i termini specifici del progetto a docs.json:

```json docs.json
{
  "spellcheck": {
    "ignore": ["YourProduct", "kubectl", "Terraform"]
  }
}
```

Il nome del progetto indicato in `docs.json` viene escluso automaticamente.

#### jamdesk openapi-check

Valida un singolo file di specifica OpenAPI.

```bash
jamdesk openapi-check openapi.yaml
jamdesk openapi-check api/spec.json
```

**Elementi validati:**

- Sintassi YAML/JSON valida
- Conformità allo schema OpenAPI 3.x
- Definizioni degli endpoint
- Risoluzione corretta dei riferimenti `$ref`

<Note>
  **Le specifiche OpenAPI vengono validate in tre punti.** `jamdesk dev` si arresta all'avvio se una specifica referenziata non è valida, mentre `jamdesk validate` / `jamdesk openapi-check` verificano le specifiche su richiesta. Durante il deploy, la build cloud valida anch'essa le specifiche referenziate, ma in quel caso si tratta di un **avviso non bloccante**: il resto della documentazione viene comunque pubblicato e ricevi informazioni precise sull'errore (un errore di analisi con riga e colonna, un `$ref` non risolto o un `operationId` duplicato) tramite email e nell'elenco delle build della dashboard. Correggi la specifica ed esegui nuovamente il push per rimuovere l'avviso.
</Note>

### Gestione dei file

#### jamdesk rename

Rinomina una pagina e aggiorna automaticamente tutti i riferimenti.

```bash
jamdesk rename docs/old-name.mdx docs/new-name.mdx
```

**Questa operazione:**

- Rinomina il file
- Aggiorna la navigazione di docs.json
- Aggiorna i link in tutti gli altri file MDX
- Aggiorna i riferimenti agli snippet

Usa questo comando invece di rinominare manualmente i file per mantenere sincronizzati tutti i riferimenti.

### Migrazione

#### jamdesk migrate

Migra la documentazione da Mintlify a Jamdesk.

```bash
jamdesk migrate
```

Rileva la configurazione Mintlify e la converte nel formato Jamdesk. Nello stesso passaggio rinomina i componenti deprecati (ad esempio `CardGroup` → `Columns`), sposta i file MDX di snippet orfani in `/snippets/` e riscrive gli import relativi al percorso padre, estrae i componenti inline che usano gli hook React in `/snippets/<name>.tsx` con `'use client'` e corregge automaticamente i problemi meccanici di sintassi MDX. L'operazione è idempotente, quindi puoi eseguirla nuovamente senza rischi.

<Card title="Guida alla migrazione" icon="right-left" href="/it/setup/migration">
  Guida completa alla migrazione passo passo per Mintlify e altre piattaforme
</Card>

### Deploy

#### jamdesk deploy

Carica la documentazione e avvia una build direttamente dal terminale.

```bash
jamdesk deploy
jamdesk deploy --detach
jamdesk deploy --full-rebuild
```

L'avanzamento viene mostrato in tempo reale al completamento di ogni fase della build. Disponibile anche come `jamdesk push`.

| Flag | Descrizione |
|------|-------------|
| `--detach` | Accoda l'operazione ed esce immediatamente |
| `--full-rebuild` | Forza una ricostruzione completa (senza cache) |
| `--project <id>` | Esegue il deploy in un progetto specifico |
| `--allow-empty` | Consente il deploy senza pagine di contenuto `.mdx` (rifiutato per impostazione predefinita) |

<Card title="Guida al deploy CLI" icon="cloud-arrow-up" href="/it/cli/deploy">
  Pipeline di deploy completa, fasi della build, riferimenti agli errori e risoluzione dei problemi
</Card>

#### jamdesk deploy-proxy cloudflare

Crea e distribuisce un Worker Cloudflare che inoltra `/docs` del tuo dominio al tuo sito Jamdesk.

```bash
jamdesk deploy-proxy cloudflare
jamdesk deploy-proxy cloudflare --slug myproject --domain example.com --yes
```

Per impostazione predefinita è interattivo: verifica Wrangler, controlla il tuo account Cloudflare, rileva automaticamente lo slug da `docs.json`, genera i file del Worker ed eventualmente esegue il deploy. Con `--yes` genera i file e si arresta: esegui il deploy con `npx wrangler deploy` dalla directory di output.

| Flag | Descrizione |
|------|-------------|
| `--slug <slug>` | Slug del progetto Jamdesk |
| `--domain <domain>` | Dominio di destinazione (ad esempio `example.com`) |
| `--path <path>` | Prefisso del percorso (predefinito: `/docs`) |
| `--output-dir <dir>` | Directory di output (predefinita: `cloudflare-worker/`) |
| `--skip-deploy` | Ignora la richiesta "eseguire ora il deploy?" in un'esecuzione interattiva |
| `--force` | Sovrascrive la directory di output se esiste già |
| `--yes` | Risponde a ogni richiesta con il valore predefinito (modalità CI). Non esegue mai il deploy né sovrascrive una directory esistente |

<Card title="Guida ai Workers Cloudflare" icon="cloud" href="/it/deploy/cloudflare">
  Configurazione del Worker, pattern delle route e configurazione della cache
</Card>

### Manutenzione

#### jamdesk doctor

Controlla l'ambiente e diagnostica i problemi.

```bash
jamdesk doctor
```

**Verifica:**

- Versione di Node.js (richiede v20+)
- Versione di npm
- Esistenza e validità di docs.json
- Stato della cache `~/.jamdesk`
- Permessi di scrittura

Esegui questo comando se riscontri problemi con la CLI.

#### jamdesk clean

Svuota la directory della cache `~/.jamdesk`.

```bash
jamdesk clean
```

Rimuove le dipendenze memorizzate nella cache e gli artefatti di build. Usalo per:

- Liberare spazio su disco
- Risolvere problemi relativi a una cache danneggiata
- Forzare una nuova installazione delle dipendenze

Le dipendenze verranno reinstallate alla successiva esecuzione di `jamdesk dev`.

#### jamdesk update

Aggiorna la CLI alla versione più recente.

```bash
jamdesk update
```

Puoi anche eseguire l'aggiornamento manualmente:

```bash
npm update -g jamdesk
```

## Configurazione

Crea `~/.jamdeskrc` per impostare le opzioni predefinite:

```json
{
  "defaultPort": 3001,
  "verbose": false,
  "checkUpdates": true
}
```

| Opzione | Tipo | Predefinito | Descrizione |
|--------|------|---------|-------------|
| `defaultPort` | number | 3000 | Porta predefinita per il server di sviluppo |
| `verbose` | boolean | false | Abilita l'output dettagliato per impostazione predefinita |
| `checkUpdates` | boolean | true | Verifica la disponibilità di aggiornamenti della CLI all'avvio |

## Risoluzione dei problemi

### Errori di sintassi MDX

I file MDX vengono analizzati come JSX, quindi alcuni caratteri hanno un significato speciale.

**Problema comune:** il carattere `<` viene interpretato come l'inizio di un tag JSX.

```text
✗ Found 1 MDX syntax error(s)

  getting-started.mdx:42
    Unexpected character `5` (U+0035) before name
    Fix: A < character is being parsed as JSX. Use &lt; or rewrite
```

**Soluzioni:**

- Usa `&lt;` per il simbolo minore letterale: `Values &lt;50% are low`
- Riscrivi il testo per evitare il carattere: `"Below 50%"` invece di `"<50%"`
- Esegui `jamdesk validate` per messaggi di errore dettagliati con i numeri di riga

### docs.json non trovato

Assicurati di trovarti in una directory contenente un file `docs.json`.

**Soluzioni:**

- Esegui `jamdesk init` per creare un nuovo progetto
- Controlla di trovarti nella directory corretta
- Verifica che il file si chiami esattamente `docs.json` (non `doc.json` o simili)

### Il server di sviluppo non si avvia

Il server di sviluppo potrebbe non avviarsi per diversi motivi.

**Prova questi passaggi:**

1. Esegui `jamdesk doctor` per controllare l'ambiente
2. Esegui `jamdesk clean` per svuotare la cache
3. Usa `jamdesk dev --verbose` per un output dettagliato degli errori
4. Verifica che Node.js v20+ sia installato: `node --version`

### Prima esecuzione lenta

La prima esecuzione installa le dipendenze in `~/.jamdesk/node_modules`.

È normale e avviene una sola volta. Le esecuzioni successive saranno molto più rapide.

### Porta già in uso

Un altro processo sta usando la porta predefinita.

**Soluzioni:**

```bash
# Use a different port
jamdesk dev --port 3001

# Or set a default in ~/.jamdeskrc
{ "defaultPort": 3001 }
```

### Errori di autorizzazione negata

Potresti non disporre dei permessi di scrittura per la directory della cache.

**Soluzioni:**

1. Controlla i permessi su `~/.jamdesk`: `ls -la ~/.jamdesk`
2. Correggi il proprietario: `sudo chown -R $(whoami) ~/.jamdesk`
3. Esegui `jamdesk clean` e riprova

**I problemi persistono?** Consulta la [guida alla risoluzione dei problemi della CLI](https://jamdesk.com/docs/it/help/troubleshooting/cli-issues) o [apri una segnalazione su GitHub](https://github.com/jamdesk/jamdesk-cli/issues).

## Qual è il prossimo passo?

<Columns cols={2}>
  <Card title="Autenticazione" icon="key" href="/it/cli/authentication">
    Flusso di accesso, sessioni e risoluzione dei problemi
  </Card>
  <Card title="Deploy CLI" icon="cloud-arrow-up" href="/it/cli/deploy">
    Esegui il deploy dal terminale
  </Card>
  <Card title="Anteprima locale" icon="eye" href="/it/development/local-preview">
    Opzioni avanzate per lo sviluppo locale
  </Card>
  <Card title="Guida alla migrazione" icon="right-left" href="/it/setup/migration">
    Migra da Mintlify o da altre piattaforme
  </Card>
</Columns>