Troubleshooting Common Problems

Use this page to diagnose common issues with BoldCreate CLI. Start with the message or behavior you see, then follow the matching steps.

Start with a quick check

Open a new terminal window and run:

boldcreate --version
boldcreate status

If the command is not recognized, check Installation and the PATH section below. If BoldCreate starts, status shows your account and current settings.

The boldcreate command is not found

macOS

The CLI is installed in ~/.local/bin. If the terminal reports command not found: boldcreate, add that directory to your PATH, then open a new terminal and try again.

Do not run the installer with sudo. It installs for the current user, and using sudo installs it for the root user instead.

Windows

The installer adds the CLI directory to your user PATH. Close the terminal window used for installation, open a new PowerShell window, and run:

boldcreate --version

Use the PowerShell installation command on Windows. The macOS shell command is not for Windows, including Git Bash.

Sign-in or account checks fail

Sign in from a terminal:

boldcreate login

If the browser does not open, copy the link printed in the terminal and open it in a browser on the same computer. After signing in, check your account with:

boldcreate status

If print mode reports boldcreate: not signed in, run boldcreate login and retry the request. In interactive chat, BoldCreate opens a sign-in prompt when needed.

status --check says a model is needed

Choose a model ID from the available list:

boldcreate --list-models

Then pass it to the check:

boldcreate status --check --model <MODEL_ID>

Model listing requires browser sign-in; it is not available when signed in with an API key. If the list is empty or a search returns No match, remove the search terms and check the full list.

A request does not run or fails

“Nothing to do” in print mode

Print mode needs a prompt or input from a pipe. Provide a prompt:

boldcreate -p "summarize README.md"

Or pipe input into the command. In PowerShell:

Get-Content error.log | boldcreate -p "explain this error"

The run fails

Read the error and its hint. For temporary service or connection errors, BoldCreate retries automatically. Press Esc to stop waiting. If a run fails, type /retry in the open chat to run the last failed request again.

BoldCreate is waiting

In manual approval mode, an action may be waiting for your approval. Respond to the approval prompt to continue. In print mode, exit code 3 means BoldCreate stopped while waiting for approval.

A file attachment is rejected

Files attached with @ must be text files no larger than 256 KB. For a larger or binary file, mention its path in your message so the agent can read it from the workspace.

An option or value is rejected

Run:

boldcreate --help

Use the values shown in the error message. An unknown option or invalid value exits with code 2; that code also indicates a wrong command or that you are not signed in.

An MCP server is missing or invalid

Check configured servers and inspect a specific one:

boldcreate mcp list
boldcreate mcp get <SERVER_NAME>

The mcp list output includes the state and reason for servers that did not start or connect. It exits with code 1 if any server is invalid, fails, or needs sign-in.

The server program cannot be found

For a command server, use the executable’s full path if it is not on PATH. On Windows, start npx through cmd /c, as shown in Connect MCP servers: examples.

If the command was added without the separator, add -- before the server program. In PowerShell, quote the separator as '--'.

A required environment variable is missing

If the server reports that a variable is not set:

1. Set the variable in the environment before starting BoldCreate.
2. Open a new terminal after setting it.
3. Ensure the variable is passed to the command server with --env when required.
4. Put ${VARIABLE} references in single quotes when adding the server so the shell does not replace them prematurely.

Keep tokens out of project configuration files. Use environment-variable references for secrets.

A server needs sign-in or returns HTTP 401

For an HTTP server that requires browser sign-in, use:

boldcreate mcp login <SERVER_NAME>

If a GitHub MCP server returns HTTP 401, check that its token is correct and not expired. Create a replacement token if necessary, then update the server configuration.

A skill is not loaded

At startup, check the Skill errors section for the reason. A usable SKILL.md needs YAML frontmatter containing both name and description; the name must match the skill folder name. Fix the file and start a new session.

A settings file warning appears

BoldCreate does not stop because of an invalid settings file; it shows a warning and ignores the invalid part.

When editing JSON by hand, keep quotes around names and text values and separate entries with commas.

A shortcut or shell command behaves differently

• If a shortcut does nothing, the terminal may capture that key. Check the terminal’s key settings; Ctrl+J can be used for a new line.
• On Windows, ! commands run through cmd.exe, not PowerShell. Use a cmd.exe command, such as !dir, instead of a PowerShell command such as !Get-ChildItem.
• If you type /agent plan while the assistant is working, wait for it to finish or press Esc before switching agents.

Exit codes