Hugging Face account and CLI

The Hugging Face Hub is where open-weight models and datasets live, and where you keep what you train. In this path you download base models from it, keep each LoRA adapter you train in a private model repo so a later exercise or a serving script can load it by name, and, when the free Kaggle quota runs out, rent a GPU by the minute with Hugging Face Jobs. The fine-tuning exercises in Fine-Tuning and RL for Agents use it next to Free GPUs on Kaggle.

Before you start

• A personal email address to sign up with. The free account is enough for everything except Jobs.
• macOS, Linux or Windows. Projects in this path use Python 3.12 and uv.
• Jobs only: pre-paid credit. Jobs are "available to any user or organization with a positive credit balance", so you add credit before the first run.

1. Create an account

Sign up at huggingface.co/join and confirm your email. Your username is the namespace of every repo you create, as in your-username/quillmoor-triage-sft.

2. Install the hf CLI

macOS and Linux

curl -LsSf https://hf.co/cli/install.sh | bash

Windows

powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

Projects that already depend on huggingface_hub get the same CLI inside their environment, so uv run hf … works there without the global install.

3. Create a least-privilege token

Open Settings → Access Tokens and choose New token. Make it fine-grained: Hugging Face recommends fine-grained tokens because a leak exposes less. Give it only what this path needs:

• write access to repos in your own namespace, so it can create private repos and upload adapters;
• the permission to start and manage Jobs, only if you will use Jobs.

Leave everything else off, and don't pick full access. Name the token after the machine it lives on: Hugging Face's own advice is one token per machine or notebook, so you can revoke one without breaking the others.

4. Sign in

hf auth login

Paste the token when asked. It's stored in your Hugging Face home folder, and the libraries and the CLI pick it up from there. Scripts and CI can use an environment variable instead:

export HF_TOKEN=hf_your_token

or a project .env file with HF_TOKEN=hf_your_token, loaded only for the scripts that need it. Keep .env in .gitignore. If a token ever leaks, delete it on the tokens page at once; anyone holding it can read and write your private repos until you do.

5. Keep adapters in a private repo

Create the repo once. --private makes it invisible to everyone else, and --exist-ok makes the command safe to re-run:

hf repos create your-username/quillmoor-triage-sft --private --exist-ok

Upload one adapter folder into its own path in the repo, with a commit message that says what it is:

hf upload your-username/quillmoor-triage-sft runs/quillmoor-sft-r16/out/checkpoints/checkpoint-32 quillmoor-sft-r16-step32 \
  --commit-message "SFT adapter, rank 16, step 32"

Download it on another machine, or inside a training run, with the same token:

hf download your-username/quillmoor-triage-sft --include "quillmoor-sft-r16-step32/*" --local-dir adapters

An adapter is small (tens to a few hundred megabytes) and useless without its base model, but treat it like code you haven't published: it encodes your data, so keep the repo private.

6. Optional: GPU Jobs, with a cap on the cost

Jobs run a script on Hugging Face's GPUs and bill by the minute while the Job is starting or running. As of November 2026 a t4-small (one T4, 16 GB) costs $0.40 an hour, an l4x1 (one L4, 24 GB, with bf16) $0.80 and an a10g-small $1.00. Run hf jobs hardware for the current list.

Hugging Face documents Jobs spending limits only for organisations' resource groups, so on a personal account build the cap yourself:

1. Pre-pay a small amount on the billing page, say $5. Jobs need a positive balance, so the credit is the most you can spend.
2. Always pass --timeout. The default is 30 minutes, which kills a long training run; an explicit timeout also stops a hung one. A Job that reaches its timeout stops billing.
3. Cancel what you don't need with hf jobs cancel <job-id>, and check the usage section of the billing page after each session.

Try the official hello-world on a T4, a few cents of compute:

hf jobs uv run --flavor t4-small --timeout 5m \
  https://raw.githubusercontent.com/huggingface/hub-docs/main/examples/jobs/hello_gpu.py

The commands you'll use for training runs:

hf jobs uv run --flavor t4-small --timeout 3h -s HF_TOKEN -v ./data:/data -d train.py   # -d returns the Job ID
hf jobs ps -a                     # your Jobs, including finished ones
hf jobs logs -f <job-id>          # stream the log; Ctrl+C stops the stream, not the Job
hf jobs inspect <job-id>          # final status and error message
hf jobs cancel <job-id>

-s HF_TOKEN forwards your token as a secret so the script can push its outputs; it reads the HF_TOKEN variable and, if that isn't set, may fall back to your saved token, so export it explicitly when in doubt. -v ./data:/data syncs a local folder to a private bucket and mounts it read-only. A Job's own disk is thrown away when it ends, so the script must push anything you want to keep, for example to the private repo from step 5.

Check it works

hf auth whoami
hf repos create your-username/hello-private --private --exist-ok

Expected: whoami prints your username, and the repo page loads at https://huggingface.co/your-username/hello-private while you're signed in but returns a 404 in a private browser window. Delete the test repo from its Settings tab afterwards.

Troubleshooting

403 Forbidden when uploading or creating a repo. The token can't write to that namespace. Edit the token's permissions on the tokens page, or create one with write access to your own repos.

A Job won't start and mentions billing or credits. Jobs need a positive credit balance. Add credit on the billing page, then run it again.

A training Job stops after 30 minutes. That's the default timeout. Pass --timeout 3h or whatever the run needs, with some margin.

hf: command not found. Open a new terminal so the installer's path change takes effect, or run it from a project with uv run hf.

Going further

• Free GPUs on Kaggle, the free option to try first
• Serve an open-weight model with vLLM, which can load a base model plus your adapters
• Run GPU code on Modal, another per-second GPU option with a monthly free credit