DEV Community

Danilo Fortunato
Danilo Fortunato

Posted on

The distribution checklist nobody writes down

#cli #github #opensource #python

I ship four small Python CLI tools. Not libraries — command-line utilities you install and run once. And I learned the hard way that building them is the easy part. The part with all the friction is putting them where someone who needs them will actually find them.

This is the checklist I wish I had, with the exact walls I hit. No theory.

1. PyPI name squatting is the first wall

My website auditor is called SiteAuditor. The PyPI name site-auditor was already taken by an unrelated project. So the distribution name and the command name had to be split:

package:  danyblitz-site-auditor
command:  siteauditor
Enter fullscreen mode Exit fullscreen mode

Two lessons:

  • Check the name before you fall in love with it. pip index versions <name> or the PyPI JSON API tells you in one second whether it is free.
  • Decide the package name and the console-script name separately. You are not forced to make them agree.

And drop the dash in the command name. photo-metaclean as a package, photometaclean as the command. A dash in a command name is friction in every doc, every alias, every shell one-liner.

2. winget needs a real release asset, not a source zip

winget installs from a URL plus a SHA256. If your GitHub release has no .exe, you cannot ship a winget package at all. The manifest is a portable one, schema 1.6.0.

Two frictions worth knowing before you start:

  • A one-time Microsoft CLA. The bot asks the account to reply @microsoft-github-policy-service agree. It is a checkbox, but nothing moves until it is done.
  • The review queue. Free, human, and unschedulable. Set expectations.

3. Directories are a queue, not a launch

SaaSHub, AlternativeTo and friends: submission is free, review is slow, and it is a queue shared with everyone else. Some offer a paid "priority review"; the free path is fine if you stop expecting same-day visibility.

The field that actually matters is alternatives. A tool with no alternatives listed is nearly invisible. Add two or three real ones and you show up where people compare tools by function.

4. The boring thing that mattered most

The highest-leverage step was the least exciting: getting the tools into the package managers. A tool that is pip install <name> away is discoverable in a way a landing page is not. My landing pages were fine for months and nobody came. The moment the packages were installable, the problem changed from "marketing" to "is the name right".

The one-line version

Publication is not discovery. A landing page pushes; it does not pull. Discovery lives in two places only:

  1. package managers (PyPI, winget, npm, Homebrew)
  2. directories where someone searches by what a tool does

Everything else — Product Hunt, a dev.to post, a tweet — is a one-day spike on top of that base.

If you want to see a finished tool of this kind: SiteAuditor audits a page and its links, Photo MetaClean strips EXIF, and both are pip install away.

Top comments (0)