Skip to contentllms.txt

Troubleshooting

Debug flags

Section titled “Debug flags”

syllago provides several flags to help diagnose problems. These work with any command.

FlagDescription
--verbose / -vVerbose output showing what syllago is doing step by step
--jsonMachine-readable JSON output for all commands
--no-colorDisable color output (also available via NO_COLOR=1 env var)
--dry-runPreview changes without writing (supported on select commands)

Combine flags for maximum visibility:

Terminal window
syllago add --from claude-code --dry-run

Common issues

Section titled “Common issues”

Provider not detected

Section titled “Provider not detected”

syllago init doesn’t find your AI coding tool.

Symptoms:

  • syllago init reports no providers found
  • Provider missing from syllago list output

Fix:

  1. Verify the tool is installed and available in your PATH:
    Terminal window
    which <tool-name>
  2. If the tool is installed but not detected, add it manually:
    Terminal window
    syllago config add <provider>
  3. Run syllago providers to see all supported providers.

Windsurf renamed to Devin Desktop

Section titled “Windsurf renamed to Devin Desktop”

Starting in syllago v0.15.0, the Windsurf provider is Devin Desktop, with the slug devin. The old slug still works as an alias, whether you type it in a command or set it in your config. Syllago prints one warning for each old slug in use:

warning: provider "windsurf" was renamed to "devin"; use "devin" instead

Replace windsurf with devin in your commands and config to stop the warning.

Global skills now install to ~/.config/devin/skills/. Skills already under ~/.codeium/windsurf/skills/ still show as installed, and you can still uninstall them. Agents install to ~/.config/devin/agents/, and hooks, which earlier releases refused to install, merge into ~/.config/devin/config.json (%APPDATA%\devin\config.json on Windows). Every other Devin Desktop path stays the same, including .windsurfrules, .windsurf/rules/, .windsurf/skills/, .windsurf/workflows/, and ~/.codeium/windsurf/.

The first time the new version runs, syllago migrates your library once. Each <type>/windsurf/ folder moves to <type>/devin/, and a link at the old path keeps existing references working. Syllago repoints the provider links and install records that used the old folder, and replaces windsurf with devin in your metadata and loadout files. It prints one notice line:

notice: migrated library content to renamed provider slugs: rules/windsurf -> rules/devin; 3 metadata and loadout files updated

If your library already has both a windsurf folder and a devin folder for the same content type, syllago moves nothing and prints a warning that names both paths. Move the items from the windsurf folder into the devin folder, then delete the windsurf folder.

Syllago doesn’t touch windsurf/ folders in projects or registry clones. It reads them as devin content.

Content not appearing after add

Section titled “Content not appearing after add”

You ran syllago add but can’t find the content.

Symptoms:

  • Content missing from expected provider config
  • syllago list shows fewer items than expected

Fix:

  1. Run syllago list to verify what’s actually imported.
  2. Check the --source filter — content may be in a different source (registry vs library):
    Terminal window
    syllago list --source registry
    syllago list --source library
  3. Run syllago list --verbose for details on where each item came from.

Format conversion issues

Section titled “Format conversion issues”

A conversion between providers fails or produces unexpected results.

Symptoms:

  • Error during syllago add, syllago install, or syllago convert
  • Content type mismatch warnings

Fix:

  1. Check syllago providers to see which content types each provider supports.
  2. Not all content types work with all providers. Verify your source and target are compatible.
  3. Check the format conversion reference for the compatibility matrix.

Related error codes:

Registry sync failures

Section titled “Registry sync failures”

syllago registry sync fails to pull updates.

Symptoms:

  • Sync command errors out
  • Registry content is stale or missing

Fix:

  1. Check network connectivity — registries are fetched over the network (typically git).
  2. Verify you have access to the registry repository.
  3. Run sync with verbose output for details:
    Terminal window
    syllago registry sync --verbose
  4. Check syllago registry list to confirm the registry URL is correct.

Related error codes:

Permission errors on install

Section titled “Permission errors on install”

syllago can’t write to the provider’s configuration directory.

Symptoms:

  • “Permission denied” errors during import or sync
  • Content fails to write to the target location

Fix:

  1. Check file permissions on the provider’s config directory.
  2. Ensure your user owns the directory, or has write access.
  3. On macOS/Linux:
    Terminal window
    ls -la ~/.config/<provider>/

Related error codes:

Error codes

Section titled “Error codes”

Every syllago error includes a code like CONVERT_001 or REGISTRY_002. Each code has a dedicated page with explanations, common causes, and fixes.

See the full error codes reference for the complete list.

Getting help

Section titled “Getting help”
  • Inline docs: Run syllago --help or syllago <command> --help for usage information on any command.
  • CLI reference: Browse the full CLI reference for detailed documentation.
  • GitHub issues: Report bugs or ask questions at github.com/OpenScribbler/syllago/issues.