Headless Mode Basics

Module: Automation | Lesson: 1 of 3 | Time: ~10 minutes

What You Will Learn

• What headless mode is and when to use it
• How to use the -p flag for non-interactive runs
• How to read and parse JSON output

Prerequisites

• Completed Module 10: Agents & Subagents

What Is Headless Mode?

Up until now, every time you have used Claude Code, you started an interactive session -- you typed claude, had a conversation, and typed /exit when you were done. That works great when you are sitting at your computer, but what if you want Claude to do something automatically? Maybe you want a script to run Claude at 2 AM, or you want Claude to process 50 files without you clicking "approve" for each one.

That is what headless mode is for. Headless mode lets you run Claude Code as a single command that takes input, does its work, and gives you output -- all without any interactive prompts or conversation. Think of it like the difference between having a phone call (interactive) and sending a text message (headless). With a text, you send your message, the other person responds, and you are done.

Why "headless"?

The term "headless" comes from the idea of running software without a "head" (a screen or user interface). A headless program runs entirely in the background, with no visible window or interactive prompt.

---

The -p Flag: Your Entry Point

The key to headless mode is the -p flag (short for "print" or "prompt"). Instead of starting an interactive session, you pass your entire prompt as a single command:

claude -p "What is the capital of France?"

Press Enter and Claude will:

1. Read your prompt
2. Think about it
3. Print the response directly to your terminal
4. Exit immediately

There is no conversation, no permission prompts, no interactive session. Claude answers and you are back at your PowerShell prompt.

Try it now. Open PowerShell and run:

claude -p "List 3 benefits of version control in one sentence each"

You should see Claude's response printed directly in your terminal, followed by your normal PowerShell prompt. No need to type /exit -- Claude already finished and closed.

info

When you use -p, Claude runs with tool permissions that allow it to read files in your current directory but it will not modify anything unless you explicitly grant permissions. This makes it safe for automation.

---

Getting JSON Output

Plain text is fine for reading, but if you want a script to process Claude's response, you need something more structured. That is where --output-format json comes in.

Try this command:

claude -p "What are the 3 primary colors?" --output-format json

Instead of plain text, you will get something like this:

{
  "type": "result",
  "subtype": "success",
  "cost_usd": 0.002,
  "is_error": false,
  "duration_ms": 1523,
  "duration_api_ms": 1200,
  "num_turns": 1,
  "result": "The three primary colors are red, blue, and yellow.",
  "session_id": "abc123..."
}

This is JSON (JavaScript Object Notation) -- a standard format that scripts and programs can easily read. The important fields are:

Field	What It Means
result	Claude's actual response text
cost_usd	How much this call cost in US dollars
is_error	Whether something went wrong (true or false)
duration_ms	How long the entire call took in milliseconds
num_turns	How many back-and-forth turns occurred

tip

You do not need to memorize all these fields. The one you will use most often is result -- that is where Claude's answer lives.

---

Combining Flags

You can combine -p with other useful flags:

# Get JSON output
claude -p "Summarize this project" --output-format json

# Use a specific model
claude -p "Explain this code" --model claude-sonnet-4-20250514

# Allow specific tools
claude -p "Read the README and summarize it" --allowedTools "Read"

---

Common Use Cases for Headless Mode

Headless mode unlocks several powerful workflows:

1. Quick one-off questions When you just need a fast answer without starting a full session:

claude -p "Convert 72 degrees Fahrenheit to Celsius"

2. Scripting and automation Your PowerShell scripts can call Claude as part of a larger workflow (we will cover this in the next lesson):

# Inside a script
$summary = claude -p "Summarize this file: $(Get-Content README.md -Raw)" --output-format json

3. CI/CD pipelines Claude can run as a step in your GitHub Actions or other automation pipelines (covered in Lesson 3):

- run: claude -p "Review this code for bugs" --output-format json

4. Batch processing Process many files or tasks in a loop without manual interaction:

Get-ChildItem *.md | ForEach-Object {
    claude -p "Summarize: $(Get-Content $_.FullName -Raw)"
}

---

Headless Mode vs Interactive Mode

Here is a quick comparison to help you decide which to use:

Feature	Interactive (claude)	Headless (claude -p)
Starts a conversation	Yes	No
Requires you to be present	Yes	No
Can be used in scripts	No	Yes
Multi-turn follow-ups	Yes	No
Permission prompts	Yes	Minimal
Best for	Exploration, complex tasks	Automation, quick queries

warning

Headless mode is powerful, but it does not give you the chance to review and approve each action the way interactive mode does. Be careful what you ask Claude to do in headless mode, especially if your prompt involves modifying files. We will cover safety considerations in Module 13.

---

Try It Yourself

Practice headless mode with these exercises:

1. Basic headless call. Run this and observe the output:

   claude -p "Write a haiku about programming"

2. JSON output. Run the same prompt with JSON output and notice the structure:

   claude -p "Write a haiku about programming" --output-format json

3. File-based prompt. Navigate to a folder that has at least one file in it, then run:

   claude -p "List all files in this directory and describe what each one might contain"

4. Save the output. Use PowerShell's redirection to save Claude's response to a file:

   claude -p "Write 5 tips for learning to code" > coding-tips.txt

   Open coding-tips.txt in File Explorer to confirm the output was saved.

5. JSON to file. Save JSON output and examine it:

   claude -p "What is PowerShell?" --output-format json > response.json

   Open response.json in a text editor and find the result field.

---

What You Learned

• Headless mode runs Claude without an interactive session using the -p flag
• --output-format json gives you structured output that scripts can parse
• The JSON response includes the result field (Claude's answer), cost, duration, and error status
• Headless mode is ideal for scripting, automation, CI/CD pipelines, and batch processing
• Interactive mode is still better for exploration and complex multi-turn tasks

---

Help Us Improve

How was this lesson? Take 2 minutes to share your feedback — it helps us make the tutorials better for everyone.

Give Feedback →

Next Up

Next: Scripting with Headless Mode