Add cli for @huggingface/hub

[coyotte508]

cc @Wauplin @hanouticelina for viz

Internal context: https://huggingface.slack.com/archives/C0256NXF0A2/p1745930278721439?thread_ts=1741697907.530409&cid=C0256NXF0A2

Also add createBranch and deleteBranch functions

Follow up to #1398

eg:

npm install -g @huggingface/hub 
export HF_TOKEN=...

# Upload current dir to coyotte508/test-model in a new empty "build" branch
hfjs create-branch coyotte508/test-model build --empty
hfjs upload coyotte508/test-model --revision build

Testing

go into packages/hub

run pnpm install

and run sudo npm link - then you can use hfjs

or just do node dist/cli.js upload ...

[HuggingFaceDocBuilderDev]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[coyotte508]

btw @Wauplin @hanouticelina do you have advice regarding the cli params?

This PR adds --from-revision and --from-empty that to the best of my knowledge are not present in the python cli

• --from-empty => hfjs upload --revision new --from-empty will create an empty branch before committing to it
• --from-revision => hfjs upload --revision new --from-revision xxx will create a branch with the last commit from xxx before committing to it

Note that we could be fancy and do like git --revision :new to create from empty, and --revision xxx:new to create new from xxx

Edit: is the hub url configurable or not with the python cli? (thinking of adding --hub-url cli param but it can be hidden)

[coyotte508]

FYI released a test version, can be gotten with sudo npm install -g @huggingface/hub@cli (and then hfjs works)

or just npx @huggingface/hub@cli upload ...

[Wauplin]

Hey, just some high-level consideration (I haven't reviewed the PR itself). I don't think that the upload command should be responsible of creating the branch if it does not exist. Currently in the Python sdk you can pass e.g. --revision refs/pr/1 but the revision has to exist prior to the call. What do you think of having a separate command hfjs create-branch --from-empty or hfjs create-branch --from-revision xxx ?

My reasoning is that parameters for branch creation is not really related to the upload itself.

Edit: is the hub url configurable or not with the python cli? (thinking of adding --hub-url cli param but it can be hidden)

Doesn't exist as a parameter no. Switching Hub url is only useful for dev purposes and in Python at least, it can be done using the HF_ENDPOINT environment variable.

[coyotte508]

What do you think of having a separate command hfjs create-branch --from-empty or hfjs create-branch --from-revision xxx ?

Sure

In that case will use --revision and --empty instead of --from-empty and --from-revision

Doesn't exist as a parameter no. Switching Hub url is only useful for dev purposes and in Python at least, it can be done using the HF_ENDPOINT environment variable.

Ok, can do the same behavior

Edit:

hfjs create-branch coyotte508/test-model build --empty
hfjs upload coyotte508/test-model --revision build

in 03e615d

[Wauplin]

Edit:

hfjs create-branch coyotte508/test-model build --empty
hfjs upload coyotte508/test-model --revision build

Let's see what others think but API looks good to me

[coyotte508]

just for viz, also added a --force param to create-branch (of course can rename params if needed)

Overwrite the branch if it already exists. Otherwise, throws an error if the branch already exists. No-ops if no revision is provided and the branch exists.

[julien-c]

Let's see what others think but API looks good to me

lgtm too

[pcuenca]

API looks good. A couple of things I saw while testing some of the stuff I do during releases with the Python CLI:

• The repo had to exist for upload to work.
• If the intention is to eventually auto-create the repo, then --private would be useful. If it's not, then we should update the help messages, as they say that repo-name is The name of the repo to create.
• create-branch --empty did not work for me. Normal branch creation worked fine.
• I find it strange that hfjs upload --help does not produce the same output as hfjs --help upload.
• (Not a priority now) Error handling could translate the API messages. For example, attempting to create a branch that already existed without using --force dumps the API error where this message is highlighted: 'Reference refs/heads/onebranch already exists. Use overwrite=true to force it.', but the user has to use --force, not overwrite=true.

[coyotte508]

Thanks for the feedback @pcuenca !

API looks good. A couple of things I saw while testing some of the stuff I do during releases with the Python CLI:

* The repo had to exist for `upload` to work.

* If the intention is to eventually auto-create the repo, then `--private` would be useful. If it's not, then we should update the help messages, as they say that `repo-name` is `The name of the repo to create`.

The plan is to have the same behavior/API as the python CLI for the features that are in both CLI. The python cli seems to automatically creates repos, we can do the same with the same API.

Still a bit sketchy to create a repo just like that, what if the user made a typo on an existing repo name 🤔 (but if consensus on adding it it can be added still)

The description of the param was updated in last commit, thank you!

* `create-branch --empty` did not work for me. Normal branch creation worked fine.

Yes there's a bug atm, see this slack: https://huggingface.slack.com/archives/C0379TL2H0E/p1746609551072829 . It'll be fixed indepently of the huggingface.js repo but I'll wait for it to be fixed before merging this PR

* I find it strange that `hfjs upload --help` does not produce the same output as `hfjs --help upload`.

Should also be fixed in last commit

* (Not a priority now) Error handling could translate the API messages. For example, attempting to create a branch that already existed without using `--force` dumps the API error where this message is highlighted: `'Reference refs/heads/onebranch already exists. Use overwrite=true to force it.'`, but the user has to use `--force`, not `overwrite=true`.

Yea, the hub would probably need to send error codes that the cli can translate into custom error messages (like is the case in the python lib for repo not found / file not found errors)

[pcuenca]

Still a bit sketchy to create a repo just like that, what if the user made a typo on an existing repo name

Yes, that's a valid concern! In practice, I've relied extensively on repo creation for programmatic upload of multiple repos during releases, and haven't had issues. We could still do it in two phases, but in my opinion it'd be nice if the two CLIs are similar.