Starlists

Starlists

Prefer the installed stars binary on PATH. Use --json when reading output. SQLite is local truth. GitHub Lists change only on apply --confirm.

First commands

command -v stars
stars --json doctor
stars init

Auth: GITHUB_TOKEN / GH_TOKEN / STARS_GITHUB_TOKEN / gh auth token. List writes need user scope (gh auth refresh -h github.com -s user).

Database default: ~/.local/share/stars/stars.db. Config: ~/.config/stars/config.toml. Proposal schema: https://github.com/chuxubank/starlists/blob/main/schema/proposal.v1.json

Safe read path

stars snapshot
stars --json lists
stars --json repos list --unlisted --limit 50
stars --json repos show owner/repo
stars export --for-agent --out /tmp/stars-corpus.json

snapshot is a network read. It updates the local DB. It does not write Lists.

Classify

1. Export corpus (export --for-agent).
2. Write proposal.json matching schema/proposal.v1.json. A repo may have multiple list slugs. Prefer existing slugs. Create a list only for a real cluster (about 4+ repos). Do not split by programming language. Keep live GitHub lists around 20–28 (cap 32).
3. Import locally:

stars --json propose import proposal.json
stars --json plan show

Stop after import. Do not write GitHub from the classifier.

Write path

Needs explicit user approval.

stars apply --plan PLAN_…
stars apply --plan PLAN_… --confirm

Without --confirm this is a dry-run. Pass --confirm or request --write only when the user asked to mutate GitHub.

Local-only edits:

stars lists create "Web Mapping" --desc "…"
stars assign owner/repo --add web-mapping --add emacs

updateUserListsForItem replaces a repo's entire list set. Apply always sends the full set. List deletes run after membership updates.

Raw hatch

stars --json request --query 'query { viewer { login } }'

Mutations require --write.

Emacs

--sexp prints data as an s-expression. Call the same binary.