Right, let’s get our hands dirty with the hugo command itself. Forget the gentle, hand-holding hugo help output; we’re going to dissect the thing you’ll be typing into your terminal a thousand times. This isn’t a list of every flag—that’s what --help is for. This is a curated tour of the flags and subcommands you’ll actually use, along with the ones that will bite you if you don’t know they’re there.

The Two Modes: Server and Build

First, wrap your head around this: hugo has two primary modes of operation, and it’s crucial you know which one you’re in.

When you run hugo server, you’re in development mode. Hugo generates your site into memory (not to disk by default, a brilliant efficiency trick), fires up a local web server, and then—this is the magic part—watches your files for changes. Make an edit to a content file or a template, and it rebuilds almost instantly and even tells your browser to live reload. It’s for you, the author.

When you run hugo (or hugo build), you’re in production mode. This renders your entire site to the public/ directory (or wherever you tell it) with all the optimizations turned on, ready to be shipped to your web host. It assumes you want the final, polished product.

Why does this matter? Because some flags behave differently depending on the mode. The most important one is…

The Environment Flag (-e or --environment)

This is arguably the most important flag you will ever use. Hugo uses this to determine which config file to use (config.toml, config.production.toml, etc.) and, more importantly, which settings to apply. Most site configurations have settings like enableGitInfo, minify, and analytics scripts that you only want enabled in your final, production build.

# Running your server for local development (the default)
hugo server -e development

# Building the final site for deployment
hugo -e production

If you don’t specify -e, it defaults to production for hugo build and development for hugo server. I know, it’s a bit inconsistent, so I always specify it explicitly to avoid any “why does my local site look different?!” panic attacks.

Controlling the Destination (-d or --destination)

By default, Hugo will chuck your built website into the public/ directory. Sometimes you want it elsewhere. Maybe you’re a masochist and want to run two builds into two different folders for comparison. This is how you do it.

hugo -d ./output_prod
hugo server -d ./public_dev

A common pitfall? Forgetting that the hugo server command also has a -d flag. It determines where it builds the site in memory. You rarely need to change this, but it’s there if you need to debug something specific.

The BaseURL Trap (--baseURL)

This setting is the source of more broken CSS and image links than any other. Your baseURL in your config file is the absolute root of your published site (e.g., https://my-brilliant-site.com/). If you’re running your server locally, you almost certainly need to override this, otherwise all your links will point to your production domain and break.

hugo server --baseURL "http://localhost:1313/"

This is a classic example of a flag you use constantly with hugo server but almost never with hugo build.

Content Management: new vs. create

This is where the designers got a little cute with synonyms. Both hugo new and hugo create do the same thing: they create new content files using your archetypes as templates.

# These two commands are functionally identical. Pick one and stick with it.
hugo new posts/my-first-post.md
hugo create posts/my-first-post.md

The -k flag lets you specify which archetype to use. So if you have an archetypes/posts.md and an archetypes/news.md, you can be explicit.

hugo new -k news press-release-about-cats.md

The best practice here? Define your archetypes thoroughly. Put all your default front matter (title, date, draft status, categories) in there. It saves you from remembering the syntax every time and ensures consistency.

The Cleanup Operation (--cleanDestinationDir)

When you run a build, Hugo doesn’t start by deleting everything in your public/ folder. It just overwrites what it needs to. This is usually fine, but sometimes you delete a content file and are surprised to find the corresponding HTML file is still sitting in public/, like a ghost from websites past. This flag tells Hugo to wipe the destination directory clean before building, ensuring only the files it intends to create are there.

hugo --cleanDestinationDir

Use this when you’re doing a final build for deployment, or if something seems deeply funky with your output. It’s the “turn it off and on again” of Hugo builds.

The Dry Run (--dryRun)

Want to see what Hugo would do without actually doing it? This flag is your best friend. It’s perfect for checking if your new content filter is working correctly or just for sanity-checking a complex build command.

hugo --dryRun

It will output a list of all the files it would create, which is a fantastic way to answer the question “is it ignoring the thing I want it to ignore?”