Troubleshooting
Last updated:
Troubleshooting
Common issues and solutions when working with Cerebro.
Command Not Found
Problem: CLI reports "Command not found" for existing command
$ my-cli build
Error: Command "build" not foundSolutions:
- Verify command is registered:
cli.addCommand({
name: "build",
execute: ({ logger }) => {
logger.log("Building...");
},
});- Check for typos in command name
- Check nested command syntax:
$ my-cli db migrate # Correct
$ my-cli db-migrate # WrongOption Validation Errors
Problem: Required option errors
$ my-cli deploy
Error: Required option --environment is missingSolution: Provide the required option:
$ my-cli deploy --environment productionOr make it optional with a default value:
{
name: "environment",
type: String,
defaultValue: "staging", // No longer required
}Conflicting Options Error
Problem: Using incompatible options together
$ my-cli test --watch --ci
Error: Options --watch and --ci conflictSolution: Use only one of the conflicting options:
$ my-cli test --watch
# or
$ my-cli test --ciType Errors
Problem: TypeScript errors for toolbox extensions
cli.addCommand({
execute: ({ myFeature }) => {
// Error: Property 'myFeature' does not exist
},
});Solution: Declare the extension type:
declare global {
namespace Cerebro {
interface ExtensionOverrides {
myFeature: {
doSomething: () => void;
};
}
}
}Plugin Initialization Issues
Problem: Plugin not working in commands
cli.use(myPlugin());
cli.addCommand({
execute: ({ myFeature }) => {
// myFeature is undefined
},
});Solutions:
- Check plugin registration order (before commands)
- Verify plugin adds to toolbox:
const myPlugin = (): Plugin => ({
name: "my-plugin",
register: async ({ toolbox }) => {
toolbox.myFeature = { doSomething: () => {} };
},
});- Check for plugin dependencies
Environment Variable Issues
Problem: Required environment variable not found
$ my-cli deploy
Error: Required environment variable API_KEY is missingSolution: Set the environment variable:
$ API_KEY=secret123 my-cli deployOr use a .env file:
# .env
API_KEY=secret123import "dotenv/config";
import { createCerebro } from "@visulima/cerebro";
// ...Help Text Not Showing
Problem: --help doesn't display help text
Solutions:
- Verify help command is registered (automatic by default)
- Add command descriptions:
cli.addCommand({
name: "build",
description: "Build the project", // Required for help
execute: ({ logger }) => {},
});- Manually register help command:
import { HelpCommand } from "@visulima/cerebro/command/help";
cli.addCommand(HelpCommand);Exit Code Issues
Problem: CLI exits with code 0 even on errors
Solution: Use error handler plugin:
import { errorHandlerPlugin } from "@visulima/cerebro/plugin/error-handler";
cli.use(errorHandlerPlugin({ exitOnError: true }));Or manually set exit code:
cli.addCommand({
name: "test",
execute: async ({ logger }) => {
try {
await runTests();
} catch (error) {
logger.error(error.message);
process.exit(1); // Exit with error code
}
},
});Performance Issues
Problem: CLI is slow to start
Solutions:
- Lazy-load heavy dependencies:
cli.addCommand({
name: "heavy",
execute: async () => {
// Load only when command runs
const { heavyFunction } = await import("./heavy-module");
await heavyFunction();
},
});- Minimize plugin initialization work
- Use dynamic imports for optional features
Cross-Runtime Issues
Problem: CLI works in Node.js but not in Deno/Bun
Solutions:
- Avoid Node.js-specific APIs
- Use Cerebro's runtime abstractions:
import { getEnv, getCwd } from "@visulima/cerebro";
cli.addCommand({
execute: ({ logger }) => {
const env = getEnv(); // Works in all runtimes
const cwd = getCwd(); // Works in all runtimes
logger.log(`CWD: ${cwd}`);
},
});- Test in all target runtimes
Debugging
Enable debug output:
CEREBRO_OUTPUT_LEVEL=debug my-cli buildAdd debug logging:
cli.addCommand({
name: "build",
execute: ({ logger }) => {
if (process.env.CEREBRO_OUTPUT_LEVEL === "debug") {
logger.log("Debug: Starting build...");
}
// Build logic
},
});