Introducing the Verso CLI

[TorreyBetts]

Starting with v1.0.12, Verso ships as a .NET global tool. One install gives you the full Verso editor in any browser, headless notebook execution for CI/CD, and format conversion between .verso, .ipynb, and .dib files.

dotnet tool install -g Verso.Cli

That's it. Every language kernel, formatter, and extension that ships with Verso is included.

Why a CLI?

Notebooks are powerful for exploration, but their value doesn't have to stop at the editor. A report built in Verso can be scheduled. A data pipeline prototyped interactively can graduate to a CI job. A teammate who doesn't use VS Code can open the exact same notebook in their browser without cloning a repo or configuring an extension.

The CLI makes all of that possible with a single tool.

Launch the Editor Anywhere

verso serve starts the full Verso editor as a local web server. No VS Code required, just a browser.

# Start the editor on the default port
verso serve

# Open a specific notebook
verso serve my-notebook.verso

# Use a custom port, skip the auto-launched browser tab
verso serve --port 8080 --no-browser

This is useful for machines where VS Code isn't installed, remote servers accessed over SSH tunnels, or anyone who prefers working in the browser.

Run Notebooks Headlessly

verso run executes a notebook from top to bottom and streams the output. No UI, no browser, just results.

# Run and see output in the terminal
verso run pipeline.verso

# Pass parameters to a parameterized notebook
verso run pipeline.verso --param region=us-east --param date=2026-04-01

# Export structured results for downstream processing
verso run pipeline.verso --output json --output-file results.json

# Stop on the first failure
verso run pipeline.verso --fail-fast

Exit codes are deterministic (0 for success, 1 for cell failure, 2 for timeout, 5 for missing parameters), so your CI system always knows what happened.

Convert Between Formats

verso convert handles format conversion without opening a notebook. Useful for migrating Jupyter or Polyglot Notebook files, or for stripping outputs before committing to version control.

# Convert a Jupyter notebook
verso convert notebook.ipynb --to verso

# Strip outputs for a clean commit
verso convert notebook.verso --to verso --strip-outputs --output notebook-clean.verso

Load Custom Extensions

All four commands accept an --extensions flag that points to a directory containing additional extension assemblies. This is how you load third-party or custom-built extensions that aren't bundled with the CLI.

# Serve with a custom extension loaded
verso serve --extensions ./my-extensions

# Run a notebook that depends on a custom kernel
verso run pipeline.verso --extensions /opt/verso-extensions

# Convert using a custom serializer
verso convert notebook.custom --to verso --extensions ./my-extensions

Extension authors ship their extensions as .NET assemblies. Drop them into a directory, point --extensions at it, and the CLI discovers and loads them automatically. This works the same way whether you're running locally or in a CI pipeline.

CI/CD Integration

GitHub Actions

steps:
  - uses: actions/checkout@v4

  - name: Setup .NET
    uses: actions/setup-dotnet@v4
    with:
      dotnet-version: '8.0.x'

  - name: Install Verso CLI
    run: dotnet tool install -g Verso.Cli

  - name: Run notebook
    run: verso run tests/integration.verso --output json --output-file results.json --fail-fast

  - name: Upload results
    uses: actions/upload-artifact@v4
    with:
      name: notebook-results
      path: results.json

Azure DevOps Pipelines

steps:
  - task: UseDotNet@2
    inputs:
      packageType: 'sdk'
      version: '8.0.x'

  - script: dotnet tool install -g Verso.Cli
    displayName: 'Install Verso CLI'

  - script: >-
      verso run pipelines/nightly-report.verso
      --param env=staging
      --output json
      --output-file $(Build.ArtifactStagingDirectory)/results.json
      --fail-fast
    displayName: 'Run notebook'

  - task: PublishBuildArtifacts@1
    inputs:
      pathToPublish: '$(Build.ArtifactStagingDirectory)/results.json'
      artifactName: 'notebook-results'

Parameterized Builds

Because notebooks support typed parameters, you can drive the same notebook across multiple configurations:

# GitHub Actions matrix example
jobs:
  regional-pipeline:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        region: [us-east, us-west, eu-west]
    steps:
      - uses: actions/checkout@v4
      - run: dotnet tool install -g Verso.Cli
      - run: >-
          verso run pipelines/regional-etl.verso
          --param region=${{ matrix.region }}
          --output json
          --output-file results-${{ matrix.region }}.json
          --fail-fast

Check Your Setup

verso info shows the installed version, .NET runtime, and all discovered extensions:

$ verso info
Verso CLI 1.0.12
Runtime:    .NET 8.0.11
Engine:     Verso 1.0.12
Extensions:
  verso.kernel.csharp          C# Kernel               1.0.12
  verso.fsharp.kernel          F# Kernel               1.0.12
  verso.python.kernel          Python Kernel            1.0.12
  verso.kernel.javascript      JavaScript Kernel        1.0.12
  verso.powershell.kernel      PowerShell Kernel        1.0.12
  verso.ado.kernel.sql         SQL Kernel               1.0.12

Get Started

dotnet tool install -g Verso.Cli
verso info

Full option reference and additional CI/CD examples are in the CLI README. If you run into issues or have feedback, open an issue or reply here.