CLI 使用指南

AtomGit CLI 用于下载、上传模型和数据集文件，以及创建仓库。当前工具基于 Hugging Face Hub SDK，安装 atomgit 包即可同时使用 atomgit 命令和 atomgit_hub Python SDK。

本文按 atomgit 1.0.17 核验，建议先升级再使用单文件下载和版本选择等功能。

安装与检查

建议在 Python 3.11 或更高版本的虚拟环境中安装：

python -m pip install -U atomgit
atomgit --version
atomgit --help

atomgit_hub 是安装 atomgit 后提供的导入模块，不需要单独安装。旧版文档中的 pip install gitcode、gitcode 命令不适用于本文的操作步骤。

如果终端找不到 atomgit 命令，可使用同一个 Python 环境执行：

python -m atomgit --version
python -m atomgit --help

需要从源码安装时，可使用官方 CLI 仓库：

git clone https://atomgit.com/gitcode-ai/atomgit_cli.git
cd atomgit_cli
python -m pip install -e .

下载模型或数据集

公开且无需申请访问的仓库可以直接下载，无需先登录。 私有或受限仓库需要具有相应读取权限的访问令牌，参见下文的登录说明。

仓库 ID 请从目标仓库页面复制。镜像仓库需要保留完整前缀，例如 hf_mirrors/Qwen/Qwen3-0.6B。

先下载单个文件

可先下载 README 或配置文件，检查访问和保存路径，再下载较大的权重文件：

atomgit download hf_mirrors/Qwen/Qwen3-0.6B README.md -d ./qwen3-check
atomgit download hf_mirrors/Qwen/Qwen3-0.6B config.json -d ./qwen3-check

第二个位置参数是仓库内的文件路径。单文件模式不指定 -d 时，文件保存到当前目录；包含子目录的文件会保留相对路径。

下载整个仓库

# 下载整个模型仓库到指定目录，包含权重文件
atomgit download hf_mirrors/Qwen/Qwen3-0.6B -d ./models/Qwen3-0.6B

# 不指定目录时，保存到当前目录下以仓库名命名的子目录
atomgit download your-username/your-model-name

下载数据集时，将仓库 ID 替换为数据集页面提供的 ID。

选择版本或重新下载

# 下载指定分支或标签中的文件；main 应替换为仓库中实际存在的版本
atomgit download hf_mirrors/Qwen/Qwen3-0.6B config.json --revision main -d ./qwen3-check

# 强制重新下载指定文件
atomgit download hf_mirrors/Qwen/Qwen3-0.6B config.json -d ./qwen3-check --force

参数	说明
`REPO_ID`	仓库页面提供的完整 ID
`FILENAME`	可选，仓库内的文件路径；省略时下载整个仓库
`-d, --directory`	本地保存目录
`-r, --revision`	分支或标签；不指定时由 SDK 解析仓库默认分支
`--force`	强制重新下载；省略时复用已下载文件，并在支持的情况下续传

查看当前安装版本的完整参数：

atomgit download --help

登录与账号管理

上传文件、创建仓库或访问私有仓库前，需要先在 AtomGit 账号设置中创建具有相应权限的访问令牌，然后登录：

atomgit login

按提示粘贴访问令牌，输入时不会回显。这里使用访问令牌，不是账号登录密码。

# 查看当前登录用户
atomgit whoami

# 查看登录状态、配置文件位置及 Git 集成状态
atomgit config-show

# 清除本地登录信息；已配置的 AtomGit Git 凭证助手也会被移除
atomgit logout

创建仓库与上传文件

将示例中的 your-username 和仓库名替换为你有权限使用的命名空间与仓库名称。目标仓库不存在时，先创建仓库：

# 创建模型仓库
atomgit repo create your-username/my-model --type model

# 创建私有数据集仓库
atomgit repo create your-username/my-dataset --type dataset --private

上传目录或单个文件：

# 上传模型目录
atomgit upload ./my-model --repo-id your-username/my-model --message "Upload model"

# 上传数据集目录，并将上传超时设为 1200 秒
atomgit upload ./my-dataset --repo-id your-username/my-dataset --timeout 1200

# 上传单个文件
atomgit upload ./README.md --repo-id your-username/my-model

upload 的 --timeout 默认值为 300 秒，可按文件大小和网络情况调整。创建数据集时使用 --type dataset；上传命令通过 --repo-id 指定目标仓库。

在 Python 中使用 SDK

SDK 与 CLI 共享登录配置。以下示例只下载 README 和配置文件，不下载完整权重：

from atomgit_hub import snapshot_download

model_dir = snapshot_download(
    "hf_mirrors/Qwen/Qwen3-0.6B",
    local_dir="./qwen3-check",
    allow_patterns=["README.md", "config.json"],
)
print(model_dir)

移除 allow_patterns 可下载完整仓库；可通过 revision 指定版本。访问私有仓库时，可先执行 atomgit login，或通过 SDK 的 token 参数传入访问令牌。

配置与 Git 集成

项目	当前路径或地址
CLI / SDK 登录配置	`~/.atomgit/config.json`
Hub 缓存目录	`~/.cache/atomgit`
默认 Hub 服务地址	`https://hub.atomgit.com`
Git 凭证助手	`~/.atomgit/git-credential-atomgit`

CLI 内部使用 HF_ENDPOINT 指向 https://hub.atomgit.com，无需手动设置。旧版 OPENMIND_HUB_ENDPOINT 和 ~/.gitcode/config.json 不用于当前工具。

登录配置以本地 JSON 文件保存访问令牌，请勿将该文件提交到仓库或共享给他人。

如果系统已安装 Git，atomgit login 会尝试为 atomgit.com 和 hub.atomgit.com 配置全局 Git 凭证助手。配置成功后，访问这些域名下的 HTTPS 仓库时可以复用令牌：

# 克隆含大文件的模型仓库前，需要安装 Git LFS 并初始化
git lfs install
git clone https://atomgit.com/hf_mirrors/Qwen/Qwen3-0.6B.git

CLI / SDK 下载通过 Hub 接口完成，不要求安装 Git LFS。若 Git 凭证配置失败，可查看登录命令的提示和 atomgit config-show 输出；CLI 登录成功不代表 Git 凭证助手一定配置成功。

常见问题

问题	处理方法
找不到 `atomgit` 命令	确认已激活安装工具的 Python 环境，或使用 `python -m atomgit`
无法导入 `atomgit_hub`	在运行代码的同一 Python 环境执行 `python -m pip install -U atomgit`；Notebook 安装后可重启内核
单文件参数或 `--revision` 无法识别	升级 `atomgit`，用 `atomgit --version` 和 `atomgit download --help` 检查实际版本及参数
返回 401 / 403	检查是否为私有或受限仓库、令牌是否有效及是否有读取或写入权限，必要时重新执行 `atomgit login`
返回 404	核对完整仓库 ID、文件路径和版本，尤其不要省略镜像仓库的 `hf_mirrors/` 前缀
上传超时	检查网络，并使用 `--timeout` 增大上传超时时间
下载中断	检查网络和磁盘空间，使用相同目录重试；需要强制重新下载时再添加 `--force`

安装与检查​

下载模型或数据集​

先下载单个文件​

下载整个仓库​

选择版本或重新下载​

登录与账号管理​

创建仓库与上传文件​

在 Python 中使用 SDK​

配置与 Git 集成​

常见问题​