Have you ever had a dev server running, and then asked your coding agent to test something in that app? It starts its own server on port 3001. Then it restarts that one, and you end up with another on 3002. Pretty soon you've lost track of what's running on which port and what you need to stop...
Nuxt CLI v4 shipped alongside Nuxt 4.6 in early October, and a few of its new features fix that exact problem. The Nuxt team pitched this release as a speed and dev experience update. Nuxt's own numbers put the CLI install at 3.5 MB (down from 13.1 MB) and first paint for nuxt dev at 50 ms (down from 330 ms). However, what I'm really interested in is some of the agentic features.
I tried them on a small Nuxt 4.6.4 todo app. Here's the video if you'd rather watch:
Prerequisites
- Node.js 22.21+, 24.11+, or 26+. CLI v4 won't run on older versions.
- A Nuxt project on 4.6 or later. CLI v4 is a dependency of
nuxt, so upgrading Nuxt gets you the new CLI. I testednuxt4.6.4 with@nuxt/cli4.0.3. - Optional, a coding agent that can run shell commands.
1. Meet the new nuxt dev
Run npm run dev and the first thing you'll notice is the panel pinned to the bottom of your terminal. It shows your Nuxt version, the local URL, a request counter, and a row of single-key shortcuts.
The new nuxt dev panel. Each letter at the bottom is a shortcut.
r restarts the server, o opens it in the browser, i shows info about your setup, and n lists every request with its status and timing. Press p for all your pages and server routes. If you'd rather have plain log output, nuxt dev --no-tui turns the panel off.
2. Check the lock file
When nuxt dev starts, it writes .nuxt/nuxt.lock. When you stop the server, the file goes away. Here's mine:
.nuxt/nuxt.lock has everything an agent needs to find the running server.
The PID, port, and URL tell an agent that a server is already up and where to find it. It doesn't have to probe ports or guess at localhost:3000.
The interactive field records whether the server was started from an interactive terminal. Nuxt uses it to decide what happens when a second nuxt dev shows up. In my testing, a server started from a real terminal wouldn't hand itself over to a non-interactive nuxt dev (the kind an agent runs). The agent gets a message pointing it at --takeover instead. A server that was started non-interactively gets taken over on the same port, so an agent that restarts its own server doesn't leave the old one running.
3. Run nuxt dev a second time
If you run npm run dev again while a server is up, Nuxt stops and asks what you want:
Taking over stops the running server. Start anyway gives you a second one.
Take over stops the running server and starts yours on the same port. That's the --takeover flag. Start anyway runs a second server, which you can also force with NUXT_IGNORE_LOCK=1. Nuxt calls that unsupported.
The CLI already warns an agent about all of this, but I still wanted the rules written down. So I added a steering file at .kiro/steering/nuxt-dev-server.md. If you use a different agent, put the same thing in AGENTS.md.
---
inclusion: always
---
# Nuxt dev server rules
This project uses Nuxt 4.6 with Nuxt CLI v4.
- Never start a second `nuxt dev`. A dev server is usually already running. Check `.nuxt/nuxt.lock` for its URL.
- Never pass `--takeover` or set `NUXT_IGNORE_LOCK=1` unless I ask.
- To test API routes, use `npx nuxt curl <path>` (add `-X`, `-d`, `-i` as needed). It finds the running server without a port.
- To run Nitro tasks, use `npx nuxt task list` and `npx nuxt task run <name> --payload.<key>=<value>`.
- Before using a Nuxt API you are unsure about, run `npx nuxt docs "<query>"` to read the docs for the installed version.
4. Test routes with nuxt curl
If the agent can't start its own server, it still needs a way to test things. That's what nuxt curl is for.
npx nuxt curl /api/todos
No host, no port. nuxt curl reads the lock file.
You pass a path, not a URL. nuxt curl reads the lock file, finds the running server, and pretty-prints the JSON it gets back. It takes the usual curl flags too, so a POST looks like this:
npx nuxt curl /api/todos -X POST -d '{"title":"Added by nuxt curl"}'
Add -i to see the response headers. If no server is running, it tells you to start one with nuxt dev or pass an absolute URL.
5. Run Nitro tasks with nuxt task
The other command I liked is nuxt task, which runs Nitro tasks against the running server. Tasks are still experimental in Nitro, so turn them on in nuxt.config.ts first:
export default defineNuxtConfig({
nitro: {
experimental: { tasks: true },
},
})
My app has a seed task in server/tasks/db/seed.ts that resets the in-memory todos:
export default defineTask({
meta: {
name: 'db:seed',
description: 'Replace the in-memory todos with N seeded todos',
},
run({ payload }) {
const count = Math.min(Math.max(Number(payload?.count) || 5, 1), 100)
const todos = resetTodos(count)
return { result: `Seeded ${todos.length} todos` }
},
})
Then list and run it from the terminal:
npx nuxt task list
npx nuxt task run db:seed
I forgot the run subcommand the first time. The help output got me there.
You can see I typed npx nuxt task db:seed first and got an error. It needs run. Pass a payload with --payload.count=10 and you get 10 todos instead of the default 5.
6. Hand errors to your agent
I really like this the most, because I run into this all the time! In my example my app has a /profile page that's broken on purpose:
<script setup lang="ts">
const user = { name: 'Erik', profile: null as null | { handle: string } }
const handle = user.profile!.handle.toUpperCase()
</script>
Load it and Nuxt shows the new error overlay. You get the error, the exact line in profile.vue, a toggle between source and compiled code, and a call stack with the 9 framework frames hidden by default.
The Copy error menu has an option written for agents.
The new part is the Copy error menu. Copy as Markdown and Copy structured JSON do what they sound like. Copy prompt for an agent wraps the error, source location, Node version, and runtime details in instructions to diagnose the error, trace the root cause, and explain the failure.
I pasted that prompt into Kiro, running Claude Opus 5.5, and let it go. Because of the steering file, it didn't start a server. It ran npx nuxt curl /profile to confirm the 500, changed the non-null assertion to optional chaining and added a v-if so the template skips the missing handle, then ran nuxt curl again to confirm a 200.
Kiro checked its own fix with nuxt curl against my running server.
The whole thing took about 36 seconds and one credit.
Wrap up
I'm really liking this new version of Nuxt CLI! I'd like to see more frameworks do this. Have you had an agent take over your dev server, or start five of them? Let me know in the comments.
Top comments (1)
Have you tried it out yet?