larksuite/cli · error · LarkCliError

Pass only one of --sheet-id or --sheet-name

Error message

Pass only one of --sheet-id or --sheet-name

What it means

run_sheets() also requires the target sheet within the spreadsheet to be identified in exactly one way: --sheet-id or --sheet-name. When both are truthy it raises LarkCliError, since the two selectors could disagree and the CLI accepts only one.

Source

Thrown at skills/lark-sheets/scripts/lark_sheet_read_cli.py:57

        cmd.append(flag if value else f"{flag}=false")
        return
    cmd.extend([flag, str(value)])


def run_sheets(
    shortcut: str,
    *,
    url: str | None = None,
    spreadsheet_token: str | None = None,
    sheet_id: str | None = None,
    sheet_name: str | None = None,
    flags: dict[str, Any] | None = None,
    timeout: int = 60,
) -> dict[str, Any]:
    if bool(url) == bool(spreadsheet_token):
        raise LarkCliError("Pass exactly one of --url or --spreadsheet-token")
    if sheet_id and sheet_name:
        raise LarkCliError("Pass only one of --sheet-id or --sheet-name")

    cmd = ["lark-cli", "sheets", shortcut]
    _append_flag(cmd, "url", url)
    _append_flag(cmd, "spreadsheet_token", spreadsheet_token)
    _append_flag(cmd, "sheet_id", sheet_id)
    _append_flag(cmd, "sheet_name", sheet_name)
    for key, value in (flags or {}).items():
        _append_flag(cmd, key, value)

    try:
        completed = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            timeout=timeout,
            check=False,
        )
    except FileNotFoundError as exc:

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Pass only sheet_id if you have it (ids are stable); drop sheet_name.
2. Pass only sheet_name if that is what the user provided; let the CLI resolve it.
3. If your code resolves the id from the name, keep only the id and remove the original name from the call.

Example fix

// before
sheet_id = lookup_id_by_name(name)
run_sheets("read", url=url, sheet_id=sheet_id, sheet_name=name)  # LarkCliError

// after
run_sheets("read", url=url, sheet_id=lookup_id_by_name(name))

if sheet_id and sheet_name:
    raise SystemExit("Provide only one of --sheet-id or --sheet-name")

def has_one_sheet_selector(sheet_id, sheet_name) -> bool:
    return bool(sheet_id) != bool(sheet_name)

try:
    data = run_sheets(shortcut, url=url, sheet_id=sheet_id, sheet_name=sheet_name)
except LarkCliError as e:
    if "only one of --sheet-id" in str(e):
        data = run_sheets(shortcut, url=url, sheet_id=sheet_id)  # prefer stable id
    else:
        raise

When it happens

Trigger: Calling run_sheets() with both sheet_id and sheet_name set, e.g. code that resolves a sheet by name but then also forwards the resolved id.

Common situations: Scripts that look up the sheet id by name and then pass both 'just in case'; users copying flags from --help output; config layers where one source supplies the id and another supplies the name.

Related errors

• Pass exactly one of --url or --spreadsheet-token
• --header-scan-rows must be at least 1
• +csv-get truncated the requested range at {source_range}; na
• lark-cli exited with {completed.returncode}
• {message}

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/de231a410d37c143. Report an issue: GitHub.