nanocoai/nanoclaw · error

unknown-command

unknown-command

Error message

unknownCommandMessage(req.command)

What it means

The ncl CLI dispatcher received a command string that does not match any registered resource/verb combination. After scanning the command table, `cmd` stayed undefined, so the request is rejected with `unknown-command` and a generated help message suggesting valid commands.

Source

Thrown at src/cli/dispatch.ts:70

  // Trimming from the end (longest→shortest) means a multi-segment verb like
  // "groups-config-add-mcp-server" still matches before any shorter prefix.
  if (!cmd) {
    let shortened = req.command;
    let idx: number;
    while ((idx = shortened.lastIndexOf('-')) > 0) {
      shortened = shortened.slice(0, idx);
      const fallback = lookup(shortened);
      if (fallback) {
        const tail = req.command.slice(shortened.length + 1); // full remainder = id, dashes intact
        cmd = fallback;
        req = { ...req, command: shortened, args: { ...req.args, id: req.args.id ?? tail } };
        break;
      }
    }
  }

  if (!cmd) {
    return err(req.id, 'unknown-command', unknownCommandMessage(req.command));
  }

  // Group-scope mechanics for agent callers (visibility, not policy — the
  // allow/hold/deny decisions live in the guard decision, cli/guard.ts).
  if (ctx.caller === 'agent') {
    const configRow = await getContainerConfig(ctx.agentGroupId);
    const cliScope = configRow?.cli_scope ?? 'group';

    if (cliScope === 'group') {
      // Auto-fill agent-group-related args so the agent doesn't need
      // to pass its own group ID explicitly.
      const fill: Record<string, unknown> = {
        agent_group_id: req.args.agent_group_id ?? ctx.agentGroupId,
        group: req.args.group ?? ctx.agentGroupId,
      };
      // Only auto-fill --id for resources where it IS the agent group ID
      // (groups, destinations). For sessions/members --id is a different key.
      if (cmd.resource === 'groups' || cmd.resource === 'destinations') {

View on GitHub (pinned to 294ef2aee8)

Solutions

1. Run `ncl help` or `ncl <resource> help` to list valid commands in this install
2. Fix the typo / use the exact verb spelling from help output
3. If the command should exist, verify the skill that registers it is installed (e.g. the channel/provider skill) and rebuild
4. Pin ncl usage in scripts to commands verified against the current version's help

Example fix

// before
ncl wirings lst
// after
ncl wirings list

const valid = await runNcl('help'); // parse the listed commands once, cache the set
if (!knownCommands.has(`${resource} ${verb}`)) {
  console.error('unknown command; run ncl help');
}

function isKnownCommand(cmd: string, known: Set<string>): boolean {
  return known.has(cmd.trim().replace(/\s+/g, ' '));
}

Catch the response and match code === 'unknown-command' to surface unknownCommandMessage() help text to the user instead of a raw error.

When it happens

Trigger: ncl requests like `ncl foo list`, `ncl groups frobnicate`, a typo (`ncl wirings lst`), or a command only registered when a channel/provider skill is installed but not present in this install.

Common situations: Typos in scripts; using a command documented on a branch/skill not installed here; version drift after update-nanoclaw removed or renamed a verb; stale shell completion.

Related errors

• Provide --apt <pkg> or --npm <pkg>
• Provide --host <host-path> and --container <container-path>
• messaging group not found: ${id}
• --threads must be true or false, got "${v}"
• provide --messaging-group-id, or --channel-type and --platfo

AI-assisted analysis of nanocoai/nanoclaw@294ef2aee8 (2026-08-28). Data as JSON: /api/errors/6628302bdd0fb7b4. Report an issue: GitHub.