larksuite / larksuite/cli

Feature request: simplify first-run setup and login flow

Open
#6 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Go
Stars
17.3k
Forks
1.4k
Avg merge
2d 4h
Merged PRs (30d)
105

Description

Summary

The first-run setup and login flow feels too complex for a new user.

Current experience

From a new user's perspective, getting to the first successful command currently involves too many steps and too much state to reason about:

  1. Install the CLI
  2. Run lark-cli config init --new
  3. Open a browser and create/configure an app
  4. Wait for app approval / availability
  5. Run lark-cli auth login
  6. Open another browser authorization page
  7. Wait for device-flow polling to finish

In practice, users may also hit unclear intermediate states such as:

  • app not configured
  • app pending approval
  • no user logged in
  • token polling still waiting

Problem

This is too much complexity for a very common goal like:

  • "I just want to try the CLI"
  • "I just want to create a Base"
  • "I just want to make my first API call"

The current flow exposes internal concepts like app creation, config initialization, approval state, and device authorization as separate steps. That may be necessary under the hood, but the UX should be much simpler.

Suggested improvements

A much simpler user experience would be something like:

npm install -g @larksuite/cli
lark-cli setup

or even:

lark-cli login

Then the CLI should guide the user through everything in one place.

Expected behavior

  • Provide a single first-run entry point such as lark-cli setup
  • Automatically handle missing config / missing app / missing login instead of requiring separate commands
  • Collapse app creation + auth into one guided flow where possible
  • Clearly distinguish these states in error messages:
    • app not created
    • app pending approval
    • user not logged in
    • authorization still waiting
  • For common tasks, offer task-oriented guidance after setup, e.g. create Base, send message, list calendar

Why this matters

The first-run experience is the highest-friction part of adoption. If it feels complicated, many users will stop before they ever see the CLI's real value.

A smoother onboarding flow would likely improve both human usage and AI-agent success rate, because the current setup requires several stateful browser/terminal handoffs.

Possible scope

Even a smaller first step would help a lot:

  • add a lark-cli setup alias that orchestrates config + auth
  • improve the error/hint messages around pending approval
  • provide one canonical "getting started" command instead of splitting the flow across multiple commands

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the existing lark-cli config init --new and lark-cli auth login entry points, including their handling of missing config, app approval, and device-flow polling. Define a bounded first-run path such as lark-cli setup, then verify that each listed state has clear guidance and that a new user can reach a first command through one canonical flow.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
authentication, cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.