CLI Quick Start Guide

For developers and data scientists who prefer working locally, our CLI tool creates a new project with all the best practices set up.

Prerequisites

To build locally, you need to install Hugo and its dependencies.

Core Requirements

• Node.js (version 18 or higher)
• Git
• Go
• Hugo Extended (The “Extended” version is required)

Install Guide

Windows

We recommend using Winget (Windows Package Manager), which comes pre-installed on Windows 10 and 11.

Open PowerShell or Terminal and run:

winget install OpenJS.NodeJS.LTS Git.Git GoLang.Go Hugo.Hugo.Extended

Note

You may need to restart your terminal after installation for the tools to be recognized.

Mac

Open Terminal and install Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Install Hugo Extended and dependencies:

brew install git golang hugo node

Linux

For Debian/Ubuntu, install all prerequisites (including Hugo Extended) via Snap:

sudo snap install --classic go node hugo

For other Linux distributions, follow the official Hugo documentation: Install from repository packages.

Tip

For installation issues, check the Hugo Community Forum.

Quick Start

Once prerequisites are installed, creating a site takes seconds.

Tip

🚚 Already have a HugoBlox site in GitHub? Import it instead of running Steps 1–2:

git clone <github_repo_url> my-site
cd my-site
npm install -g hugoblox
hugoblox dev

The my-site suffix keeps your folder name consistent with the rest of this guide—swap it for any folder name you prefer.

Then jump to Step 3 to start your local server.

1. Run the Create Command

   Open your terminal and run:

   npm create hugoblox@latest

2. Follow the Prompts

   The CLI will ask you:

   • What type of site you want to build (e.g., Academic, Blog, Landing Page)
   • Where to create the folder

3. Start the Local Server

   The CLI will ask if you want to start the local server to preview your site.

   Your site will be available at http://localhost:1313 (or similar port).

4. Customize with HugoBlox Studio

   Open your new project folder in VS Code.

   Install the HugoBlox Studio extension to visually configure your site without editing YAML files.

Next Steps

• Customize your site
• Learn about Content Blocks
• Deploy your site

---

🙋 Installation Troubleshooting & FAQ

Error: 'hugo' is not recognized as a command?

This usually means Hugo wasn't added to your system's PATH or you need to restart your terminal. Solution: Close and reopen your terminal window. If it still fails, try reinstalling Hugo (e.g., winget install Hugo.Hugo.Extended on Windows) and ensure you have administrative privileges.

Why do I need 'Hugo Extended'? Can I use standard Hugo?

You must use Hugo Extended. HugoBlox uses Tailwind to process styles, which is not included in the standard version. If you see errors about resource not found in locations or SCSS, you likely have the wrong version installed. Run hugo version to check—it should say extended.

I get an error about 'PostCSS' or 'Javascript' not found?

This happens if Node.js is missing or outdated. HugoBlox uses Node libraries to optimize your site's assets. Solution: Install the latest LTS version of Node.js (v18+) and ensure it's in your PATH.

Why is Git required?

HugoBlox is built on Hugo Modules, which uses Git under the hood to download and update themes. Even if you don't use Git for your own version control, Hugo needs it installed to fetch the HugoBlox components.

Windows: 'running scripts is disabled on this system'?

This is a PowerShell security restriction. Solution: Open PowerShell as Administrator and run Set-ExecutionPolicy RemoteSigned. This allows you to run local scripts (like the HugoBlox installer) while blocking malicious remote ones.

Mac: 'App cannot be opened because the developer cannot be verified'?

MacOS Gatekeeper sometimes blocks command line tools. Solution: Go to System Settings > Privacy & Security and look for the 'Allow anyway' button next to the blocked app notification. Alternatively, use brew install hugo which usually bypasses this issue.

How do I upgrade HugoBlox later?

Upgrading is easy because we use Go modules. Just run npx hugoblox@latest upgrade in your project folder. This will update the core theme modules to the latest version without breaking your content.