### Get CLI help with npx zapcircle --help and command-specific help

Source: https://zapcircle.com/reference/command-line

Shows how to get help for the CLI or a specific command. The example uses 'analyze' and the output displays usage, description, and the -h/--help option.

```bash
npx zapcircle --help
```

```bash
npx zapcircle <command> --help
```

```bash
npx zapcircle analyze --help
```

```text
Usage: zapcircle analyze <filetype> <path>


Analyze the provided file or directory for <filetype> - such as jsx


Options:
  -h, --help  display help for command
```

--------------------------------

### Example Output of zapcircle configure

Source: https://zapcircle.com/guides/getting-started

Example output from the `npx zapcircle configure` command. Shows the interactive prompts for provider selection, model names, API keys, and local LLM base URL, ending with confirmation that the configuration is saved to ~/.zapcircle/zapcircle.cli.toml.

```text
🛠️ Configuring ZapCircle CLI...


Preferred Provider (openai): openai
Large model (default: gpt-4o): gpt-4o
Small model (default: gpt-4o-mini): gpt-4o-mini


🔑 Enter API keys for the providers you want to use.
OpenAI API key (optional): sk-***********
Anthropic API key (optional):
Google API key (optional):
Local LLM base URL (optional): http://localhost:1234


Configuring ZapCircle CLI...
🛠️ Configuring ZapCircle CLI...


Preferred Provider (openai):
OpenAI API key (optional): SK-********
OpenAI large model (gpt-4.1):
OpenAI small model (o4-mini): o3-mini
Anthropic API key (optional):
Anthropic large model (claude-3-7-sonnet-latest):
Anthropic small model (claude-3-5-haiku-latest):
Google API key (optional):
Google large model (gemini-2.0-flash):
Google small model (gemini-2.0-flash):
Local LLM base URL (http://localhost:1234): http://localhost:1234


✅ Configuration saved to ~/.zapcircle/zapcircle.cli.toml
```

--------------------------------

### Example output from npx zapcircle new

Source: https://zapcircle.com/guides/new-project

Example terminal output showing the interactive scaffolding process. It includes prompts, generated file previews, and next steps. Actual output varies due to LLM-driven generation.

```text
💡 Let's define your new project
What are you building? A soothing mindfulness application that lets me keep track of my moods through the day
📦 Creating base Vite + React + TS project at ./mindful-moods...
📄 Created project.zap.toml
🧠 Here's your generated project.zap.toml:
  1 | name = "MindfulMoodTracker"
  2 | description = "A soothing mindfulness application..."
... (more lines)
✏️  Press Enter to continue once you've reviewed or edited the project.zap.toml
🔍 Scaffolding behaviors...
🧠 Example behavior file: MoodLogger.tsx.zap.toml
  1 | name = "MoodLogger"
  2 | role = "Logs mood entries from the user"
... (more lines)
✏️  Press Enter to continue once you've reviewed or edited this behavior file
⚙️ Generating components...
🧪 Running TypeScript check...
✅ TypeScript check passed
🔍 LLM Validation: Everything looks good
✅ Project scaffolding complete!
👉 Next steps:
   - Run the dev server: `npm run dev`
   - Edit components in `src/`
   - Modify behavior files and run: `npx zapcircle generate`
   - Get AI-assisted feedback with: `npx zapcircle review`
```

--------------------------------

### Example output of agent status

Source: https://zapcircle.com/guides/working-with-agent

Example output from `npx zapcircle agent status`. Shows the format of the issue backlog with priority and status indicators.

```text
📋 Current Issues


1) Add Remember Me checkbox (medium) [🆕 new]
2) Update Profile Form validation (high) [✅ done]
3) Add password strength meter (low) [🆕 new]
```

--------------------------------

### Example Output of zapcircle status

Source: https://zapcircle.com/guides/getting-started

Example output from the `npx zapcircle status` command. Displays the user configuration including default provider, API key status, model names for each provider, local LLM base URL, and indicates whether a project-level config file is present.

```text
📦 ZapCircle Configuration Status:


🔧 User Configuration:
  Default Provider: openai


  [openai]
    API Key: ✅ Configured
    Large Model: gpt-4o
    Small Model: gpt-4o-mini


  [anthropic]
    API Key: ✅ Configured
    Large Model: claude-3
    Small Model: claude-3-haiku


  [google]
    API Key: ✅ Configured
    Large Model: gemini-2.0-flash
    Small Model: gemini-2.0-flash


  [local]
    Base URL: ✅ http://localhost:1234


📁 Project Configuration: ❌ Not Found


✅ Status check complete.
```

--------------------------------

### Example generated .zap.toml behavior file

Source: https://zapcircle.com/guides/create-behaviors

Example of a generated .zap.toml file for a Counter component. It contains a `name` field and two multi-line string fields: `behavior` and `edgeCases`, which hold the LLM-generated analysis.

```toml
name = "counter"
behavior = """


- **Functionality**: The `Counter` component allows users to increment and decrement a numeric count displayed in the UI.
- **Initial State**: The count starts at `0`.
- **User Interaction**: Users can interact with the component by clicking the "+" and "-" buttons to change the count.
- **Reactivity**: The component re-renders each time the state is updated, showing the current count value in the `<h1>` element.
- **Potential Improvement**: To handle rapid state updates correctly, the `setCount` function should be used in a way that considers the previous state.


Overall, the `Counter` component is a straightforward implementation of a counter, demonstrating basic React state management and event handling principles."""
edgeCases = """
When analyzing the provided React component, `Counter`, various edge cases can be identified that should be tested to ensure the component behaves correctly under different conditions. Here are some potential edge cases to consider:


1. **Initial State**:
   - Test that the initial count is `0` when the component is first rendered.


2. **Incrementing Count**:
   - Test that clicking the "+" button increments the count correctly.
   - Test that multiple increments (e.g., clicking the "+" button multiple times in quick succession) updates the count accurately.


3. **Decrementing Count**:
   - Test that clicking the "-" button decrements the count correctly.
   - Test that multiple decrements (e.g., clicking the "-" button multiple times in quick succession) updates the count accurately.


4. **Handling Negative Counts**:
   - Test that the counter can go negative when decrementing from `0`. Ensure that the count displays `-1`, `-2`, etc.
"""
```

--------------------------------

### Output from zapcircle update

Source: https://zapcircle.com/reference/command-line

Example output from the update command. Confirms the component was updated and shows the path.

```text
Component updated: ./src/components/LoginForm.jsx
```

--------------------------------

### Output from zapcircle context

Source: https://zapcircle.com/reference/command-line

Example output from the context command. Shows the context file creation and the estimated token count.

```text
Running ZapCircle Context...
Context file created: zapcircle.context.txt
Estimated token count: 142978
```

--------------------------------

### Example agent issue TOML file

Source: https://zapcircle.com/guides/working-with-agent

Example issue file created by the `agent chat` interface. Shows the TOML structure with metadata, description, and comments.

```toml
id = 41
source = "chat"
status = "pending"
priority = "High"
title = "Fix login redirect after successful auth"
description = """
Users are not being redirected after logging in.
The LoginForm component should redirect to /dashboard on success.
"""
createdAt = "2025-05-13T13:00:00Z"
author = "jeff.linwood"


[[comments]]
author = "jeff.linwood"
createdAt = "2025-05-13T13:01:00Z"
body = "Seems related to LoginForm.jsx"


[[comments]]
author = "alex.smith"
createdAt = "2025-05-13T13:02:00Z"
body = "Possibly missing useNavigate hook?"
```

--------------------------------

### Verify ZapCircle Installation with npx

Source: https://zapcircle.com/guides/getting-started

Verifies that ZapCircle is installed and accessible via npx. If installed correctly, this prints the current version of ZapCircle.

```bash
npx zapcircle --version
```

--------------------------------

### Example issue request for agent chat

Source: https://zapcircle.com/guides/working-with-agent

Example user request for the `agent chat` command. This text is converted into a structured issue and queued for agent processing.

```text
Add a Remember Me checkbox to the LoginForm so users can stay logged in.
```

--------------------------------

### Output from zapcircle generateTests

Source: https://zapcircle.com/reference/command-line

Example output from the generateTests command. Shows the filetype, the .zap.toml file, and the source code path.

```text
Generating tests "jsx" from "./behaviors/LoginForm.jsx.zap.toml" for "./src/components/LoginForm.jsx"
```

--------------------------------

### Run ZapCircle distill command

Source: https://zapcircle.com/reference/command-line

The first command shows the general usage of the distill command with a placeholder for the path to the source code. The second command is a concrete example that runs distill on the current directory. The output shows the expected console messages after successful execution, including the creation of the zapcircle.distill.toml file.

```bash
npx zapcircle distill <pathToCode>
```

```bash
npx zapcircle distill .
```

```plaintext
Running ZapCircle Distill...
Distill completed: zapcircle.distill.toml
```

--------------------------------

### Start pair programming with agent pair

Source: https://zapcircle.com/guides/working-with-agent

Starts the full pair programming loop. ZapCircle reads the issue, proposes a plan, asks for approval, updates behavior files, generates code, reviews with `zapcircle review`, and shows diffs before writing files.

```bash
npx zapcircle agent pair
```

--------------------------------

### Output from zapcircle generate

Source: https://zapcircle.com/reference/command-line

Example output from the generate command. Shows the filetype and the path to the .zap.toml file being used.

```text
Generating "jsx" from "./behaviors/LoginForm.jsx.zap.toml"...
```

--------------------------------

### Generate a JSX component from a .zap.toml file

Source: https://zapcircle.com/reference/command-line

Example of generating a JSX component from a .zap.toml behavior specification file.

```bash
npx zapcircle generate jsx ./behaviors/LoginForm.jsx.zap.toml
```

--------------------------------

### Analyze a JSX file with zapcircle

Source: https://zapcircle.com/reference/command-line

Example of running the analyze command on a JSX file. This is a typical usage of the CLI.

```bash
npx zapcircle analyze jsx ./UserDashboard.jsx
```

--------------------------------

### Example generated project.zap.toml

Source: https://zapcircle.com/guides/new-project

This TOML file is generated by `zapcircle new` and defines the project's name, description, layout, state, components, data, interaction flow, build settings, and design theme. It is used to create behavior files and generate the source code.

```toml
name = "MindfulMoodTracker"
description = "A soothing mindfulness application for tracking and visualizing moods throughout the day."


[layout]
structure = "SPA"
framework = "React"
cssFramework = "Tailwind"


[state]
sharedStates = [
  { name = "moodEntries", type = "Array<Object>", description = "A list of mood entries recorded by the user" },
  { name = "selectedMood", type = "String", description = "Currently selected mood for a new entry" }
]


[[components]]
name = "MoodLogger"
role = "Logs mood entries from the user"
inputs = ["selectedMood"]
behavior = "Displays mood options and allows the user to add a new mood entry"
providesState = ["moodEntries"]


[[components]]
name = "MoodVisualizer"
role = "Visualizes mood entries over time"
inputs = ["moodEntries"]
behavior = "Renders a graphical representation of mood entries to provide insights"


[[components]]
name = "MoodSelector"
role = "Selects a mood for logging"
inputs = []
behavior = "Presents mood options and allows the user to select one to log"


[[data]]
name = "MockMoodData"
shape = "Array<Object>"
fields = ["date", "mood", "note"]
description = "Mock data for mood entries used for testing"


[interaction]
stateFlow = "MoodLogger uses selectedMood to update moodEntries. MoodVisualizer receives moodEntries. MoodSelector updates selectedMood."
propsFlow = "selectedMood passed from MoodSelector to MoodLogger. moodEntries passed to MoodVisualizer."
contextUsage = false


[build]
componentsDirectory = "./src/components"


[design]
userInterfaceTheme = "Soothing and calming"
primaryColor = "#4A90E2"
secondaryColor = "#50E3C2"
fontFamily = "Quicksand, sans-serif"
```

--------------------------------

### Analyze a directory of JSX components

Source: https://zapcircle.com/reference/command-line

Example of analyzing a directory of JSX components. The command inspects the provided path for static analysis.

```bash
npx zapcircle analyze jsx ./src/components
```

--------------------------------

### Generate context file for current directory

Source: https://zapcircle.com/reference/command-line

Example of running the context command on the current directory. Creates a zapcircle.context.txt file in the current working directory.

```bash
npx zapcircle context .
```

--------------------------------

### Output from zapcircle analyze

Source: https://zapcircle.com/reference/command-line

Example output from the analyze command when analyzing a directory. Shows the filetype and path being analyzed.

```text
Analyzing filetype "jsx" for the path "./src/components"...
```

--------------------------------

### Generate tests for a JSX component

Source: https://zapcircle.com/reference/command-line

Example of generating tests for a JSX component from a .zap.toml behavior specification.

```bash
npx zapcircle generateTests jsx ./behaviors/LoginForm.jsx.zap.toml ./src/components/LoginForm.jsx
```

--------------------------------

### Update a JSX component from a .zap.toml file

Source: https://zapcircle.com/reference/command-line

Example of updating a JSX component based on a modified .zap.toml behavior specification.

```bash
npx zapcircle update ./src/components/LoginForm.jsx.zap.toml ./src/components/LoginForm.jsx
```

--------------------------------

### Check ZapCircle Configuration Status

Source: https://zapcircle.com/guides/getting-started

Confirms your ZapCircle setup. Shows the configured provider, model names for large and small tasks, API key status for each provider, local LLM settings, and whether a project-level config file is present.

```bash
npx zapcircle status
```

--------------------------------

### Run Local Code Review with npx zapcircle review

Source: https://zapcircle.com/

Run this command in any Git project to get LLM-powered, behavior-aware code review comments before creating a pull request. It can also be integrated into a pre-commit workflow or CI pipeline.

```bash
npx zapcircle review
```

--------------------------------

### Custom JSX prompt template

Source: https://zapcircle.com/guides/customizing-prompts

Example custom prompt template for JSX generation. It uses ${name} and ${behavior} placeholders that are interpolated with values from the behavior TOML file and config. This prompt will be used instead of ZapCircle's default prompt when generating JSX.

```text
You are a helpful assistant writing React components.


Component name: ${name}
Component behavior:
${behavior}


Generate a functional JSX component with comments and minimal dependencies.
```

--------------------------------

### Create an issue with agent chat

Source: https://zapcircle.com/guides/working-with-agent

Starts an interactive chat to create a new agent issue. The agent will prompt with 'What’s the problem you’d like help with?' and convert your request into a structured TOML issue stored in `.zapcircle/agent/issues/`.

```bash
npx zapcircle agent chat
```

--------------------------------

### Generated LoginForm test file

Source: https://zapcircle.com/guides/generating-tests

Example of the test file generated by ZapCircle for a LoginForm component. It includes tests for rendering, validation, and form submission using Jest and React Testing Library.

```javascript
const React = require('react');
const { render, screen, fireEvent, waitFor } = require('@testing-library/react');
const LoginForm = require('./LoginForm');


beforeEach(() => {
  jest.clearAllMocks();
});


describe('LoginForm', () => {
  test('renders email and password inputs and login button', () => {
    render(<LoginForm />);
    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
    expect(screen.getByPlaceholderText(/enter your email/i)).toBeInTheDocument();
    expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
    expect(screen.getByPlaceholderText(/enter your password/i)).toBeInTheDocument();
    expect(screen.getByRole('button', { name: /login/i })).toBeInTheDocument();
  });


  test('displays required validation errors when fields are empty on submit', async () => {
    render(<LoginForm />);
    fireEvent.click(screen.getByRole('button', { name: /login/i }));
    expect(await screen.findByText(/email is required/i)).toBeInTheDocument();
    expect(await screen.findByText(/password is required/i)).toBeInTheDocument();
  });


  test('displays invalid email format error', async () => {
    render(<LoginForm />);
    fireEvent.change(screen.getByPlaceholderText(/enter your email/i), { target: { value: 'invalidemail' } });
    fireEvent.change(screen.getByPlaceholderText(/enter your password/i), { target: { value: 'password123' } });
    fireEvent.click(screen.getByRole('button', { name: /login/i }));
    expect(await screen.findByText(/please enter a valid email address/i)).toBeInTheDocument();
  });


  test('displays password minimum length error', async () => {
    render(<LoginForm />);
    fireEvent.change(screen.getByPlaceholderText(/enter your email/i), { target: { value: 'user@example.com' } });
    fireEvent.change(screen.getByPlaceholderText(/enter your password/i), { target: { value: 'short' } });
    fireEvent.click(screen.getByRole('button', { name: /login/i }));
    expect(await screen.findByText(/password must be at least 8 characters/i)).toBeInTheDocument();
  });


  test('login button is disabled when form is invalid', () => {
    render(<LoginForm />);
    const loginButton = screen.getByRole('button', { name: /login/i });
    expect(loginButton).toBeDisabled();
    fireEvent.change(screen.getByPlaceholderText(/enter your email/i), { target: { value: 'user@example.com' } });
    fireEvent.change(screen.getByPlaceholderText(/enter your password/i), { target: { value: 'pass' } });
    expect(loginButton).toBeDisabled();
  });


  test('login button is enabled when form is valid', () => {
    render(<LoginForm />);
    const loginButton = screen.getByRole('button', { name: /login/i });
    fireEvent.change(screen.getByPlaceholderText(/enter your email/i), { target: { value: 'user@example.com' } });
    fireEvent.change(screen.getByPlaceholderText(/enter your password/i), { target: { value: 'password123' } });
    expect(loginButton).not.toBeDisabled();
  });


  test('submits form with correct payload and handles successful login', async () => {
    global.fetch = jest.fn(() =>
      Promise.resolve({
        status: 200,
      })
    );
    delete window.location;
    window.location = { href: '' };
    render(<LoginForm />);
    fireEvent.change(screen.getByPlaceholderText(/enter your email/i), { target: { value: 'user@example.com' } });
    fireEvent.change(screen.getByPlaceholderText(/enter your password/i), { target: { value: 'password123' } });
    fireEvent.click(screen.getByRole('button', { name: /login/i }));
    await waitFor(() => expect(global.fetch).toHaveBeenCalledWith('/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: 'user@example.com', password: 'password123' }),
    }));
    await waitFor(() => expect(window.location.href).toBe('/dashboard'));
  });
```

--------------------------------

### Generated LoginForm.jsx React component

Source: https://zapcircle.com/guides/generating-code

This is the JSX React component generated by ZapCircle after calling out to an LLM. It includes form validation for email and password, submission handling via fetch to '/login', and error handling for 401 and other errors. The component uses React hooks (useState, useHistory) and is a starting point for common login form behaviors.

```jsx
import React, { useState } from 'react';
import { useHistory } from 'react-router-dom';


const LoginForm = () => {
  const history = useHistory();
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState('');
  const [loading, setLoading] = useState(false);
  const [formErrors, setFormErrors] = useState({ email: '', password: '' });


  const validateEmail = (email) => {
    const format = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return format.test(email);
  };


  const validateForm = () => {
    const errors = { email: '', password: '' };
    if (!email) {
      errors.email = 'Email is required';
    } else if (!validateEmail(email)) {
      errors.email = 'Please enter a valid email address';
    }
    if (!password) {
      errors.password = 'Password is required';
    } else if (password.length < 8) {
      errors.password = 'Password must be at least 8 characters long';
    }
    return errors;
  };


  const handleSubmit = async (e) => {
    e.preventDefault();
    const errors = validateForm();
    if (errors.email || errors.password) {
      setFormErrors(errors);
      return;
    }
    setFormErrors({ email: '', password: '' });
    setLoading(true);
    setError('');


    try {
      const response = await fetch('/login', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ email, password }),
      });


      if (response.ok) {
        history.push('/dashboard');
      } else {
        const errorResponse = await response.json();
        if (response.status === 401) {
          setError('Invalid email or password.');
        } else {
          setError('Something went wrong. Please try again later.');
        }
      }
    } catch (err) {
      setError('Something went wrong. Please try again later.');
    } finally {
      setLoading(false);
    }
  };


  return (
    <form onSubmit={handleSubmit} noValidate>
      <div>
        <label htmlFor="email">Email</label>
        <input
          type="email"
          id="email"
          placeholder="Enter your email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          aria-describedby="emailError"
        />
        {formErrors.email && <span id="emailError" style={{ color: 'red' }}>{formErrors.email}</span>}
      </div>
      <div>
        <label htmlFor="password">Password</label>
        <input
          type="password"
          id="password"
          placeholder="Enter your password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          aria-describedby="passwordError"
        />
        {formErrors.password && <span id="passwordError" style={{ color: 'red' }}>{formErrors.password}</span>}
      </div>
      {error && <div style={{ color: 'red' }}>{error}</div>}
      <button type="submit" disabled={loading || formErrors.email || formErrors.password}>
        {loading ? <span className="spinner" /> : 'Login'}
      </button>
    </form>
  );
};


export default LoginForm;

```

--------------------------------

### Run npx zapcircle init

Source: https://zapcircle.com/reference/command-line

Run the init command to create a new ZapCircle project configuration file in the current directory.

```bash
npx zapcircle init
```

--------------------------------

### Output of npx zapcircle init

Source: https://zapcircle.com/reference/command-line

Output from running npx zapcircle init, confirming the creation of the configuration file.

```text
Initializing new ZapCircle project...
ZapCircle project initialized. Configuration file created at ./zapcircle.config.toml

```

--------------------------------

### Run ZapCircle CLI with general syntax

Source: https://zapcircle.com/reference/command-line

Shows the general syntax for running the ZapCircle CLI. Replace <command> with a specific command such as analyze, generate, generateTests, update, or context, and <arguments> with the required arguments for that command.

```bash
npx zapcircle <command> <arguments>
```

--------------------------------

### Run zapcircle new with a project prompt

Source: https://zapcircle.com/guides/new-project

Use this command to generate a new Zapcircle project. The prompt describes the app's purpose and desired visual style, which the tool uses to create the project structure and configuration.

```bash
npx zapcircle new mood-tracker "I'm building a mood tracker app that lets users log how they're feeling each day. I'd like a calming visual style, with soft blue and green colors, and a rounded look. The layout should be centered and minimalist."
```

--------------------------------

### Run ZapCircle Configuration Wizard

Source: https://zapcircle.com/guides/getting-started

Runs the interactive configuration wizard for ZapCircle. You will be prompted to set your preferred LLM provider, model names, API keys, and optionally a base URL for a local LLM.

```bash
npx zapcircle configure
```

--------------------------------

### Generate a new React project with npx zapcircle new

Source: https://zapcircle.com/guides/new-project

Run this command to create a new React application. The project type `react-tsx` is required, and the directory must be empty or not yet created. If you omit the description, ZapCircle prompts you interactively.

```bash
npx zapcircle new react-tsx my-app-directory "A calming mood tracker with soft colors and a centered layout"
```

--------------------------------

### Run ZapCircle review command

Source: https://zapcircle.com/reference/command-line

The first block shows the basic usage of the review command and the variant with the --github flag, which posts results to GitHub. The output block shows the console messages when running the review, including fetching changed files, analyzing modified files, and posting a PR review when the --github flag is used.

```bash
npx zapcircle review
npx zapcircle review --github
```

```plaintext
Running ZapCircle Review...
🔍 Fetching changed files...
🧐 Analyzing 1 modified files...
🔎 Reviewing src/components/Dashboard.tsx...
Processing... done!
✅ No issues found in src/components/Dashboard.tsx. Skipping from report.
📢 Generating summary...
Processing... done!
📢 Posting PR review...
...LLM Response
```

--------------------------------

### Run ZapCircle new command

Source: https://zapcircle.com/reference/command-line

The first block shows the usage of the new command with the react-tsx project type and the current directory as the target. The output block shows the interactive prompts and the full console output when generating a new project, including the LLM validation report and the list of generated files.

```bash
npx zapcircle new react-tsx .
```

```plaintext
Running ZapCircle New...
A project.zap.toml file already exists. Use it? (Y/n): n
What are you building? A database to keep track of the dogs I walk, along with how many miles each one has gone for the month for my doggy walking business.
Processing... done!
📄 Overwrote /Users/jefflinwood/Projects/zc-examples/zc-new/project.zap.toml
Processing... done!
🧩 Wrote App.tsx
🧩 Wrote DogList.tsx
🧩 Wrote DogDetails.tsx
🧩 Wrote AddDogForm.tsx
🧩 Wrote StatsOverview.tsx
✅ All components and App.tsx generated successfully.
🧪 Running TypeScript check...
✅ TypeScript check passed with no compile-time errors.
🔍 Sending source code to LLM for validation...
Processing... done!


🧠 LLM Validation Report:


Everything seems fine with the implementation. All prop names being passed between components match correctly, state handling is logical, and the components are structured in a maintainable way. The code should work as intended without any modifications.
✅ No fixes returned. Project looks good.
✅ Project scaffolding complete!
👉 You can now run your app or customize App.tsx and the components.
```

--------------------------------

### Usage syntax for zapcircle context

Source: https://zapcircle.com/reference/command-line

Usage syntax for the context command. Replace <pathToCode> with the path to the source code of the project.

```bash
npx zapcircle context <pathToCode>
```

--------------------------------

### ZapCircle Configuration File Path

Source: https://zapcircle.com/guides/getting-started

Path to the TOML configuration file where ZapCircle stores your settings after running the configuration wizard.

```text
~/.zapcircle/zapcircle.cli.toml
```

--------------------------------

### Run ZapCircle review with --github flag

Source: https://zapcircle.com/guides/reviewing-changes

Pass the `--github` flag to send the review output to GitHub instead of the console. This is typically used in a GitHub Action.

```bash
npx zapcircle review --github

```

--------------------------------

### Generated zapcircle.config.toml

Source: https://zapcircle.com/reference/command-line

Generated zapcircle.config.toml file with default settings. Contains empty prompt templates and a filetype.generate section.

```toml
# ZapCircle Project Configuration
[prompts]
all = ""
analyze = ""
generate = ""


[filetype.generate]

```

--------------------------------

### Sample GitHub Actions workflow for ZapCircle review

Source: https://zapcircle.com/guides/reviewing-changes

GitHub Actions workflow YAML that runs ZapCircle review on pull requests. Requires an `OPENAI_API_KEY` repository secret and the `pull-requests: write` permission to post comments. Place in `.github/workflows` as `zapcircle-review.yml`.

```yaml
name: ZapCircle Review


on:
  pull_request:
    types: [opened, synchronize, reopened]


permissions:
  pull-requests: write  # REQUIRED for posting comments


jobs:
  zapcircle_review:
    name: ZapCircle PR Review
    runs-on: ubuntu-latest


    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0


      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20


      - name: Install ZapCircle CLI
        run: npm install -g zapcircle


      - name: Run ZapCircle Review
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          npx zapcircle review --github

```

--------------------------------

### Add default prompt values in zapcircle.config.toml

Source: https://zapcircle.com/guides/customizing-prompts

Configuration in zapcircle.config.toml to add default prompt values. The 'all' value becomes ${global_prompt} and the 'generate' value becomes ${generate_prompt} inside prompt templates.

```toml
[prompts]
all = "Always write clean, readable code."
generate = "Use Tailwind CSS and follow accessibility best practices."
```

--------------------------------

### Usage syntax for zapcircle generateTests

Source: https://zapcircle.com/reference/command-line

Usage syntax for the generateTests command. Replace <filetype> with the test file type, <pathToToml> with the .zap.toml behavior file, and <pathToCode> with the source code to be tested.

```bash
npx zapcircle generateTests <filetype> <pathToToml> <pathToCode>
```

--------------------------------

### ZapCircle config file for prompt variables

Source: https://zapcircle.com/guides/customizing-prompts

Configuration file from which ZapCircle loads extra prompt variables. These variables are merged with those from the .zap.toml file and are available as ${global_prompt} and ${generate_prompt} in prompt templates.

```text
zapcircle.config.toml
```

--------------------------------

### Run ZapCircle generate command

Source: https://zapcircle.com/guides/customizing-prompts

Runs the ZapCircle generate command for a JSX component. The command looks for a matching prompt file in the project's .zapcircle/prompts/generate/jsx.txt, falls back to the built-in default prompt if not found, loads extra prompt variables from zapcircle.config.toml, and interpolates ${...} placeholders in the prompt file with values from the behavior TOML file and config.

```bash
npx zapcircle generate jsx ./MyComponent.zap.toml
```

--------------------------------

### new

Source: https://zapcircle.com/reference/command-line

Creates a new project based on an idea prompt. Builds on top of existing project scaffolders, so it only generates the React components, not the supporting files such as package.json or other configuration files. Currently, the only project option to create is react-tsx, which generates React TSX components, including App.tsx. This feature should be considered experimental, as it is more complicated than some of the other features of ZapCircle. In addition, you may need to hand edit some of the generated files to fix minor errors, even with the addition of the validation step.

```APIDOC
## Command: zapcircle new

### Description
Creates a new project based on an idea prompt. Builds on top of existing project scaffolders, so it only generates the React components, not the supporting files such as `package.json` or other configuration files. Currently, the only project option to create is `react-tsx`, which generates React TSX components, including App.tsx. This feature should be considered experimental, as it is more complicated than some of the other features of ZapCircle. In addition, you may need to hand edit some of the generated files to fix minor errors, even with the addition of the validation step.

### Usage
```
npx zapcircle new react-tsx .
```

### Options
- `--verbose`: Logs the LLM prompt and response to the console.

### Example
```
npx zapcircle new react-tsx .
```

### Output
```plaintext
Running ZapCircle New...
A project.zap.toml file already exists. Use it? (Y/n): n
What are you building? A database to keep track of the dogs I walk, along with how many miles each one has gone for the month for my doggy walking business.
Processing... done!
📄 Overwrote /Users/jefflinwood/Projects/zc-examples/zc-new/project.zap.toml
Processing... done!
🧩 Wrote App.tsx
🧩 Wrote DogList.tsx
🧩 Wrote DogDetails.tsx
🧩 Wrote AddDogForm.tsx
🧩 Wrote StatsOverview.tsx
✅ All components and App.tsx generated successfully.
🧪 Running TypeScript check...
✅ TypeScript check passed with no compile-time errors.
🔍 Sending source code to LLM for validation...
Processing... done!

🧠 LLM Validation Report:


Everything seems fine with the implementation. All prop names being passed between components match correctly, state handling is logical, and the components are structured in a maintainable way. The code should work as intended without any modifications.
✅ No fixes returned. Project looks good.
✅ Project scaffolding complete!
👉 You can now run your app or customize App.tsx and the components.
```
```

--------------------------------

### Prompt folder structure for custom prompts

Source: https://zapcircle.com/guides/customizing-prompts

Folder structure for overriding or adding custom prompts in a ZapCircle project. Each file should be a .txt template with variable placeholders like ${behavior}, ${name}, etc.

```text
.zapcircle/
└── prompts/
    ├── generate/
    │   ├── jsx.txt
    │   └── tsx.txt
    └── analyze/
        └── jsx.txt
```

--------------------------------

### Run ZapCircle review command

Source: https://zapcircle.com/guides/reviewing-changes

Run the `zapcircle review` command to analyze files modified since the last commit to main. The output is written to the console.

```bash
npx zapcircle review

```

--------------------------------

### Usage syntax for zapcircle generate

Source: https://zapcircle.com/reference/command-line

Usage syntax for the generate command. Replace <filetype> with the file type (e.g., jsx, ts) and <pathToToml> with the path to the .zap.toml behavior specification file.

```bash
npx zapcircle generate <filetype> <pathToToml>
```

--------------------------------

### Create LoginForm.jsx.zap.toml with behavior specification

Source: https://zapcircle.com/guides/generating-code

Defines the LoginForm component's behavior in a TOML file, including input fields, buttons, API integration, UI states, accessibility, events, and testing requirements. This file is used as input for the generate command.

```toml
name = "LoginForm"
behavior = """
  # LoginForm Behavior Specification


  ## Overview
  The `LoginForm` component collects user credentials (email and password) and submits them to the `/login` API endpoint. It displays error messages for invalid inputs and server-side errors and redirects to a dashboard upon successful login.


  ## Input Fields
  - **Email Field**
    - Type: Email
    - Placeholder: "Enter your email"
    - Validations:
      - Required: "Email is required"
      - Format: "Please enter a valid email address"


  - **Password Field**
    - Type: Password
    - Placeholder: "Enter your password"
    - Validations:
      - Required: "Password is required"
      - Minimum Length: 8 characters


  ## Buttons
  - **Login Button**
    - Label: "Login"
    - Disabled State:
      - Disabled if either email or password is invalid.


  ## API Integration
  - **POST /login**
    - Payload:
      ```json
      {
        "email": "user@example.com",
        "password": "password123"
      }
      ```
    - Success Response:
      - HTTP Status: 200
      - Action: Redirect to `/dashboard`
    - Error Response:
      - HTTP Status: 401
      - Action: Display "Invalid email or password."
      - HTTP Status: 500
      - Action: Display "Something went wrong. Please try again later."


  ## UI States
  - **Loading State**
    - Display a spinner on the login button.
    - Disable all inputs and buttons.


  - **Error State**
    - Display error messages near the corresponding input fields or as a global error message.


  ## Accessibility
  - Ensure all inputs and buttons are accessible via keyboard navigation.
  - Associate error messages with inputs using `aria-describedby`.


  ## Events
  - **Form Submission**
    - Triggered on button click or `Enter` key press.
    - Validates inputs and sends a POST request to `/login`.


  ## Testing
  - Unit Tests:
    - Validate input fields render correctly.
    - Ensure validations are triggered on form submission.
    - Verify API calls with correct payload.
    - Test handling of API responses.
  - Integration Tests:
    - Simulate user interaction and check end-to-end flow.
"""
```

--------------------------------

### Run generateTests command

Source: https://zapcircle.com/guides/generating-tests

Use this command to generate tests for a JSX component. It requires the path to the behavior file (.zap.toml) and the source code file. Currently assumes the jest testing framework.

```bash
npx zapcircle generateTests jsx ./LoginForm.jsx.zap.toml ./LoginForm.jsx
```

--------------------------------

### Usage syntax for zapcircle update

Source: https://zapcircle.com/reference/command-line

Usage syntax for the update command. Replace <pathToToml> with the .zap.toml behavior file and <pathToCode> with the source code to be updated.

```bash
npx zapcircle update <pathToToml> <pathToCode>
```

--------------------------------

### Usage syntax for zapcircle analyze

Source: https://zapcircle.com/reference/command-line

Usage syntax for the analyze command. Replace <filetype> with the file type (e.g., jsx, tsx) and <path> with the file or directory path to analyze.

```bash
npx zapcircle analyze <filetype> <path>
```

--------------------------------

### Run an agent task with agent run

Source: https://zapcircle.com/guides/working-with-agent

Runs an agent task on an existing issue. You pick which issue to run; ZapCircle attempts to generate code and review it. Best for small, incremental tasks.

```bash
npx zapcircle agent run
```

--------------------------------

### Analyze JSX components with npx zapcircle analyze

Source: https://zapcircle.com/guides/create-behaviors

Run this command from the project root to analyze all JSX React components in the current directory. ZapCircle finds each component and processes it, generating behavior files.

```bash
npx zapcircle analyze jsx .
```

--------------------------------

### Test: displays loading state during API call

Source: https://zapcircle.com/guides/generating-tests

Mocks fetch to return a pending promise, verifies the loading state (button text, disabled fields), then resolves the fetch and checks navigation to '/dashboard'.

```javascript
test('displays loading state during API call', async () => {
    let resolveFetch;
    global.fetch = jest.fn(() => new Promise((resolve) => { resolveFetch = resolve; }));
    render(<LoginForm />);
    fireEvent.change(screen.getByPlaceholderText(/enter your email/i), { target: { value: 'user@example.com' } });
    fireEvent.change(screen.getByPlaceholderText(/enter your password/i), { target: { value: 'password123' } });
    fireEvent.click(screen.getByRole('button', { name: /login/i }));
    expect(screen.getByRole('button', { name: /loading\.\.\./i })).toBeInTheDocument();
    expect(screen.getByPlaceholderText(/enter your email/i)).toBeDisabled();
    expect(screen.getByPlaceholderText(/enter your password/i)).toBeDisabled();
    expect(screen.getByRole('button', { name: /loading\.\.\./i })).toBeDisabled();
    resolveFetch({ status: 200 });
    await waitFor(() => expect(window.location.href).toBe('/dashboard'));
  });
```

--------------------------------

### Run zapcircle update command

Source: https://zapcircle.com/guides/updating-code

Run the update command with the behavior file and source code file paths. The command applies changes from the .zap.toml file since the last git commit to the source code. The source file is overwritten, so commit your work with git before running.

```bash
npx zapcircle update ./LoginForm.jsx.zap.toml ./LoginForm.jsx

```

--------------------------------

### Generate JSX component with npx zapcircle generate jsx

Source: https://zapcircle.com/guides/generating-code

Runs the ZapCircle CLI to generate a React component from the specified .zap.toml file. The command uses the 'jsx' format and the file path as an argument.

```bash
npx zapcircle generate jsx ./LoginForm.jsx.zap.toml
```

--------------------------------

### Define SubmitButton behavior in .zap.toml

Source: https://zapcircle.com/concepts/behavior-driven-development

Defines the behavior specification for the SubmitButton component in a .zap.toml file. The behavior field contains a multi-line string listing the expected behaviors. This file is used by ZapCircle to generate the component and its tests.

```toml
name = "SubmitButton"
behavior = """
- Validate form inputs on click.
- Display a success message on valid submission.
- Show an error message for invalid inputs.
"""

```

--------------------------------

### review

Source: https://zapcircle.com/reference/command-line

Reviews any code that has been modified based on a git diff - can be used from the command line, or within a GitHub Action for a pull request. Uses an LLM to spot issues with individual files, and also asks for a summary review from an LLM for general stylistic details. The --github option will post the results to GitHub to appear within a pull request; otherwise, the output appears on the console.

```APIDOC
## Command: zapcircle review

### Description
Reviews any code that has been modified based on a `git diff` - can be used from the command line, or within a GitHub Action for a pull request. Uses an LLM to spot issues with individual files, and also asks for a summary review from an LLM for general stylistic details. The `--github` option will post the results to GitHub to appear within a pull request. Otherwise, the output appears on the console.

### Usage
```
npx zapcircle review
npx zapcircle review --github
```

### Options
- `--verbose`: Logs the LLM prompt and response to the console.
- `--github`: Formats the issues and summary for GitHub, and posts to GitHub - use this flag within a GitHub action.

### Example
```
npx zapcircle review
```

### Output
```plaintext
Running ZapCircle Review...
🔍 Fetching changed files...
🧐 Analyzing 1 modified files...
🔎 Reviewing src/components/Dashboard.tsx...
Processing... done!
✅ No issues found in src/components/Dashboard.tsx. Skipping from report.
📢 Generating summary...
Processing... done!
📢 Posting PR review...
...LLM Response
```
```

--------------------------------

### Define LoginForm Behavior in .zap.toml

Source: https://zapcircle.com/

Defines the behavior for a LoginForm component in a .zap.toml file. The behavior string describes the expected functionality, which ZapCircle uses to generate the React component.

```toml
name = "LoginForm"
behavior = """
Display an email and password input. Validate that both fields are filled.
Show an error if login fails. Submit form on Enter.
"""
```

--------------------------------

### Built-in default JSX prompt path

Source: https://zapcircle.com/guides/customizing-prompts

Path to the built-in default prompt for JSX generation in the ZapCircle source code on GitHub. This is used as a fallback when the project does not have a custom prompt file at .zapcircle/prompts/generate/jsx.txt.

```text
zapcircle/src/prompts/generate/jsx.txt
```

--------------------------------

### View open issues with agent status

Source: https://zapcircle.com/guides/working-with-agent

Displays the current issue backlog. Output shows a numbered list with priority and status labels (e.g., [🆕 new], [✅ done]). Issues are not synced with external trackers yet.

```bash
npx zapcircle agent status
```

--------------------------------

### Check ZapCircle CLI version with npx zapcircle --version

Source: https://zapcircle.com/reference/command-line

Displays the current version of the ZapCircle CLI. The output shows the version number, e.g., 1.0.0.

```bash
npx zapcircle --version
```

```text
1.0.0
```

--------------------------------

### Custom prompt file path for JSX generation

Source: https://zapcircle.com/guides/customizing-prompts

Path to the custom prompt file that ZapCircle looks for when running the generate command for JSX. If this file does not exist, ZapCircle falls back to the built-in default prompt bundled in the zapcircle command, which can be seen in the source code at zapcircle/src/prompts/generate/jsx.txt.

```text
.zapcircle/prompts/generate/jsx.txt
```

--------------------------------

### Agent issues storage directory

Source: https://zapcircle.com/guides/working-with-agent

Directory where all agent issues are stored. Each issue is a simple TOML file that can be edited or version controlled.

```text
.zapcircle/agent/issues/
```