How the HKUDS/CLI-Anything Builder Handles Missing or Unknown Style Tokens

The CLI-Anything builder treats unrecognized style tokens as non-fatal warnings, logging them via console.warn and continuing execution with the remaining valid tokens.

The HKUDS/CLI-Anything repository provides a sketch integration that processes style tokens to configure CLI behavior. When users supply invalid or unsupported style identifiers, the builder employs a graceful degradation strategy rather than failing the entire command.

Where the Style Token Validation Occurs

The core validation logic resides in sketch/agent-harness/src/builder.js. During command construction, the builder iterates over each supplied style token and checks it against an internal registry of known styles.

When a token fails to match any registered entry, the builder executes this warning:

console.warn(`Unknown style token: ${style}`);

Behavior After Detecting an Unknown Token

The builder does not throw or halt execution. Instead, it:

1. Emits the warning message to stderr via console.warn
2. Excludes the invalid token from the final command payload
3. Continues processing remaining tokens normally

This pattern prevents cascading failures from typos or deprecated style names while keeping users informed.

Practical Example: Unknown Style Token in Action

The following demonstration shows how the builder responds when encountering nonexistent-style:

// Invoke CLI with an invalid style token
cli.run([
  "sketch", "export",
  "--style", "nonexistent-style",   // <-- not recognized
  "--output", "my-design.svg"
]);

Console output:

Unknown style token: nonexistent-style

The command proceeds using default styling since no valid override tokens were supplied.

Code Path for Style Token Processing

The warning emission occurs during the token normalization phase in sketch/agent-harness/src/builder.js. The builder's lookup logic follows this approximate structure:

// Simplified representation of the builder's token validation
for (const style of styleTokens) {
  if (!styleRegistry.has(style)) {
    console.warn(`Unknown style token: ${style}`);
    continue;  // Skip to next token without throwing
  }
  // Apply valid style to command configuration...
}

Why This Design Matters

Graceful degradation ensures CLI tooling remains operational even with malformed input. The alternative—throwing on first unknown token—would frustrate users during:

• Migration periods when style names change
• Partial configurations where some tokens are environment-specific
• Rapid iteration on sketch templates without full style registries

By isolating the warning to a single console.warn call in builder.js, the maintainers provide clear extension points: teams can patch the warning hook or redirect it to structured logging without modifying error-handling logic elsewhere.

Summary

• Location: sketch/agent-harness/src/builder.js contains the token validation and warning logic
• Mechanism: console.warn with interpolated token name
• Continue behavior: Execution proceeds, omitting invalid tokens
• User benefit: Commands remain functional with immediate feedback for corrections

Frequently Asked Questions

Does the CLI-Anything builder ever throw errors for style tokens?

No. According to the source implementation, unknown style tokens trigger only console.warn. The builder deliberately avoids throwing to maintain command continuity.

Can I customize the warning message for unknown style tokens?

The warning is hardcoded in builder.js as a template literal: `Unknown style token: ${style}`. To customize output, you would need to fork or patch this specific file in sketch/agent-harness/src/.

What happens if all supplied style tokens are unknown?

The builder emits one warning per invalid token, then executes the command with no style overrides applied. This typically falls back to default styling behavior defined by the sketch runtime.

Is there a way to list valid style tokens before running commands?

The analysis does not reveal an explicit enumeration command in builder.js. Valid tokens are checked against an internal styleRegistry—exposing this registry would require additional tooling not present in the core builder implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}