Feature request: simplify first-run setup and login flow
Nobody has claimed this yet.
- 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:
- Install the CLI
- Run
lark-cli config init --new - Open a browser and create/configure an app
- Wait for app approval / availability
- Run
lark-cli auth login - Open another browser authorization page
- 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 setupalias 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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