Personal access tokens are one of those setup steps that look small until you watch someone try to get through them.
The CLI says: create a GitHub token.
The user immediately has to answer questions the product may not have answered:
- Classic or fine-grained?
- Which scopes or repository permissions?
- Does "repo access" mean all repos or one selected repo?
- Why does GitHub return 404 when the repo exists?
- Is this a bad token, a bad permission, or a bad URL?
That was the problem we worked through for imdone-cli 0.70.0.
imdone turns Jira or GitHub issues into local Markdown so engineers can work with story context in their repo. For GitHub users, the first useful proof loop is simple:
imdone init
# inspect backlog/current-sprint/
# edit one markdown issue
imdone push
imdone init handles the first provider sync as part of setup. After that, imdone pull is how you refresh provider context when you want the latest issue state.
But that proof loop depends on setup being trustworthy.
The hidden problem: GitHub 404 can mean permission failure
One confusing thing about fine-grained GitHub tokens is that a repo can look like it does not exist when the token simply cannot see it.
From the user's point of view, that feels like the tool is broken. From the API's point of view, it may just be protecting access details.
The setup prompt has to account for that.
It is not enough to say "create a fine-grained token." The product should tell the user to select the right resource owner, choose the specific repository, and grant the permissions the workflow actually needs.
Classic and fine-grained tokens need different guidance
Classic tokens are broad and familiar. Fine-grained tokens are better scoped, but they add more choices.
For imdone, the prompt now has to explain the path clearly enough that the user can finish setup without searching:
- create a classic token or a fine-grained token
- grant repository access to the repo imdone will sync
- allow the issue, content, and pull-request permissions needed by the sync path
- understand that optional email lookup is only used to prefill a contact email during setup when available
The exact wording matters because the user is making a security decision.
The prompt is product surface
The bigger lesson is that setup guidance belongs in the flow.
Docs are useful, but a link to generic docs is not the same as answering the question in the moment.
If your CLI needs a token, the prompt should make the expected token shape obvious. If a common API failure is caused by repository access, the error path should say that. If there are two supported token styles, do not imply there is only one.
What changed in imdone-cli
imdone-cli 0.70.0 tightened the GitHub setup path:
- direct token creation links
- clearer classic and fine-grained permission guidance
- explicit repository-selection guidance
- SSH remote support during
imdone initandimdone clone - REST fallback when a fine-grained token cannot use the GraphQL search path
- clearer setup and push summaries
None of that is the core value of imdone.
The core value is getting real issue context into local Markdown and syncing work back to GitHub or Jira.
But if setup makes the engineer guess, they never reach that moment.
Takeaway
For developer tools, the first proof loop matters.
Help someone complete one real action:
- connect the real system
- inspect real provider data locally
- make one small change
- push it back
Everything in setup should protect that loop.
Try the imdone-cli GitHub setup path:
