chenhg5/cc-connect · error

unknown top-level command: %s

Error message

unknown top-level command: %s

What it means

validateNoExtraTopLevelArgs rejects any positional argument left over after flag parsing of the top-level cc-connect command. cc-connect has no anonymous top-level operands, so any leftover argument is reported as an unknown top-level command. It is raised from main (and an anonymous caller) when argv contains an unrecognized first token.

Source

Thrown at cmd/cc-connect/main.go:1440

	}

	return rootCLIOptions{
		configPath:     *configPath,
		force:          *force,
		observe:        *observe,
		observeChannel: *observeChannel,
		logMaxSize:     *logMaxSize,
		logMaxBackups:  *logMaxBackups,
		showVersion:    *showVersion,
		args:           fs.Args(),
	}, nil
}

func validateNoExtraTopLevelArgs(args []string) error {
	if len(args) == 0 {
		return nil
	}
	return fmt.Errorf("unknown top-level command: %s", args[0])
}

// sessionStorePath builds a unique filename from project name + work_dir.
// It checks for legacy session files (without the sessions/ subdirectory) in dataDir
// for backward compatibility; if found, uses that path. Otherwise uses dataDir/sessions/.
func sessionStorePath(dataDir, name, workDir string) string {
	var filename string
	if workDir == "" {
		filename = name + ".json"
	} else {
		abs, err := filepath.Abs(workDir)
		if err != nil {
			abs = workDir
		}
		h := sha256.Sum256([]byte(abs))
		short := hex.EncodeToString(h[:4])
		filename = fmt.Sprintf("%s_%s.json", name, short)
	}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Run `cc-connect --help` and use one of the listed subcommands.
2. Fix the typo in the subcommand name.
3. Check the installed version supports the subcommand (upgrade or downgrade cc-connect).
4. Remove stray positional arguments or extra flags placed after subcommand parsing.

Example fix

// before
cc-connect serv --config config.toml
// error: unknown top-level command: serv
// after
cc-connect serve --config config.toml

valid := map[string]bool{"serve": true, "doctor": true, "provider": true, "version": true, "help": true}
if len(os.Args) > 1 && !valid[os.Args[1]] {
    fmt.Fprintf(os.Stderr, "unknown command %q; run 'cc-connect --help'\n", os.Args[1])
    os.Exit(2)
}

if err := validateNoExtraTopLevelArgs(flagset.Args()); err != nil {
    fmt.Fprintln(os.Stderr, err)
    fmt.Fprintln(os.Stderr, "Run 'cc-connect --help' for usage.")
    os.Exit(2)
}

When it happens

Trigger: Running `cc-connect foo` or `cc-connect start-daemon-extra` where the first non-flag argument does not match a registered subcommand (serve, doctor, provider, etc.).

Common situations: Typos like `cc-connect serv`; running an old subcommand removed in a newer version; pasting a command from docs of a different tool; quoting mistakes that merge tokens.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• claudeSession: start: %w
• copilot: %q CLI not found in PATH, please install it first
• %s
• iflow process failed: %w
• iflow API request failed

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/09930da471d2faf6. Report an issue: GitHub.