`zmk download` as an alias to `gh run download`

[aadcg]

I'm new to ZMK and I think that there's a better way to fetch the artifact (firmware) of a GitHub action.

Instead of running zmk download, which only slightly eases the process, I have been running gh run download which fetches the latest artifact.

In more detail, here's my workflow:

• push changes;
• check that CI has finished successfully via gh run list -L 5;
• ensure that a folder named firmware doesn't exist and run gh run download;
• flash.

Note that gh run download may take a --repo flag and an id of the action as an argument. This ensures that a deterministic call is achievable.

What do you think?

[joelspadin]

We currently don't assume you have GitHub CLI installed, though it wouldn't be hard to check and do something different if it's installed. I do think it might be confusing if zmk download has completely different behaviors depending on whether another tool is installed though. Maybe we could add an optional argument to select a download method, and the "auto" behavior is to use gh if it's installed?

The other thing we'd need to decide is where to store the downloaded files. Should they go in the current working directory or be placed in the config repo? Should it overwrite existing files or create unique names with each download?

[aadcg]

We currently don't assume you have GitHub CLI installed

The getting started docs mention GitHub CLI. As a new user, it surprised me that ZMK leads users to get GitHub CLI while not fully leveraging it.

At https://zmk.dev/docs/zmk-cli#push-changes-to-github, it is mentioned that you need it to push a commit to a repository (which is a bit odd). I think that ZMK CLI requires GitHub CLI to automagically create the repository for the user.

https://zmk.dev/docs/user-setup#authenticate-with-github-cli also mandates installing GitHub CLI.

Maybe we could add an optional argument to select a download method, and the "auto" behavior is to use gh if it's installed?

Sounds reasonable.

The other thing we'd need to decide is where to store the downloaded files. Should they go in the current working directory or be placed in the config repo? Should it overwrite existing files or create unique names with each download?

I'd say that it should go to the config repo and overwrite existing files. The latter may seem a bit controversial. My reasoning is that generating the firmware is like compiling a program and the default behavior is to overwrite the output. Note that the artifacts are still available from GitHub.

QMK also overwrites the firmware on each compilation cycle.

[joelspadin]

The getting started docs mention GitHub CLI. As a new user, it surprised me that ZMK leads users to get GitHub CLI while not fully leveraging it.

Two reasons for this:

1. You need to authenticate with GitHub, and this seems to me like the easiest way to do it. The personal access token method is a bit involved and might be difficult for a non-technical user.
2. I want all the core features of this tool to work regardless of what service you choose to host your code on. I've intentionally designed the code to have a generic interface for service-specific features (see

   zmk-cli/zmk/remote.py

   Line 26 in f2f7a30

   match p.platform:

   ), but where possible I want to do everything with plain Git commands so special cases aren't needed for each service.

At https://zmk.dev/docs/zmk-cli#push-changes-to-github, it is mentioned that you need it to push a commit to a repository (which is a bit odd).

I'm not sure I understand why you think it is odd that you would need to push changes after making them. I don't think ZMK CLI should be automatically creating and pushing changes for you every time you change something using it, if that's what you mean.

https://zmk.dev/docs/user-setup#authenticate-with-github-cli also mandates installing GitHub CLI.

Look at the section before that:

There are several ways to do this, but the following two are the simplest. Pick whichever seems easiest to you:

I'd say that it should go to the config repo and overwrite existing files.

We'll need to decide exactly where in the config repo it should be stored, then update the .gitignore so the downloaded files don't get committed back to your repo. Some people are just going to have a single .uf2 file, in which case dropping it in the root of the repo would probably be fine, but that might result in a bit of clutter if you have a bunch of keyboards you're building, so should the files be put in a specific folder instead?

[aadcg]

@joelspadin, there was a misunderstanding regarding Github authentication from my side and, given your answer, it all became clear. In short, I assumed that creating a Github account and manually adding SSH keys to be "basic" knowledge. I didn't even know that Github CLI can do that for the user. It does make sense to assume the least from new users and instruct them accordingly.

I'm not sure I understand why you think it is odd that you would need to push changes after making them. I don't think ZMK CLI should be automatically creating and pushing changes for you every time you change something using it, if that's what you mean.

What I found strange was the idea that Github CLI (gh auth login) was needed before issuing git push for the first time. In light of my paragraph above, it should now be clear to you.

---

We'll need to decide exactly where in the config repo it should be stored, then update the .gitignore so the downloaded files don't get committed back to your repo. Some people are just going to have a single .uf2 file, in which case dropping it in the root of the repo would probably be fine, but that might result in a bit of clutter if you have a bunch of keyboards you're building, so should the files be put in a specific folder instead?

Dropping them into a folders sounds like a good idea. Candidate names would be firmware or bin.