TOD - TheOneDev CLI Tool
TOD (TheOneDev) is a powerful command-line tool for OneDev 16.9.5+
that streamlines your development workflow by letting you run CI/CD jobs
against local changes, check out pull requests into a local working
directory, query and edit issues/PRs/builds, and drive all of the above from
AI agents via shipped skill files.
Features
- Query and edit OneDev entities — issues, pull requests, and builds —
directly from the shell. - Inspect build diagnostics including logs, recent changes, and code
problem reports. - Run CI/CD jobs against local changes, branches, or tags with real-time
log streaming (tod build run --local,--branch, or--tag). - Check out issues and pull requests locally (
tod issue checkout,
tod pr checkout), including already retrieved submodules. - Check and migrate
.onedev-buildspec.ymlto the latest version
(tod build check-spec). - Agent skills under
skills/that teach Claude Code, Cursor,
and other SKILL.md-aware agents to drive OneDev workflows viatod. - Cross-platform support (Windows, macOS, Linux).
Installation
macOS, Linux, and FreeBSD```bash
curl -fsSL 'https://code.onedev.io/onedev/tod/~raw?revision=main&file=install.sh' | bash
The script detects your platform and architecture, downloads the matching
binary, and installs it to a directory on your `PATH` (overwriting an existing
`tod` if one is already installed). To choose a different location, set
`INSTALL_DIR`:```bash
curl -fsSL 'https://code.onedev.io/onedev/tod/~raw?revision=main&file=install.sh' | INSTALL_DIR="$HOME/bin" bash
Windows```powershell
irm 'https://code.onedev.io/onedev/tod/~raw?revision=main&file=install.ps1' | iex
The script downloads `tod.exe` for your architecture and installs it to a
directory on your `PATH` (overwriting an existing install if found). To choose
a different location:```powershell
$env:INSTALL_DIR = "$HOME\bin"; irm 'https://code.onedev.io/onedev/tod/~raw?revision=main&file=install.ps1' | iex
Build from source
Requirements: Go 1.22.1 or higher.```bash
git clone https://code.onedev.io/onedev/tod.git
cd tod
go build
## Configuration
Run `tod config set` to create or update the config file interactively. Each
property is prompted for in turn — the current server URL is shown in
`[brackets]` as a default (press Enter to keep it, or type a new value to
replace it), and the access-token prompt is always blank (press Enter to
keep the existing token, or type a new one to replace it):```bash
tod config set
# OneDev server URL [https://onedev.example.com]: ...
# OneDev personal access token (press Enter to keep existing): ...
For scripts and other non-interactive setups, pass the property name and
value positionally to update one property at a time without prompts:```bash
tod config set server-url https://onedev.example.com
tod config set access-token your-personal-access-token
tod config set trust-certs-file /path/to/trust-certs.pem
`tod config get` prints the active configuration (with the token redacted)
and `tod config get ` prints a single property. Property
names are `server-url`, `access-token`, and `trust-certs-file`.
`tod config path` prints the path being used.
Set `trust-certs-file` when the OneDev server uses a self-signed certificate
or a CA root not trusted by your system. The file should contain one or more
Base64 encoded PEM certificates, beginning with
`-----BEGIN CERTIFICATE-----` and ending with `-----END CERTIFICATE-----`.
The config file is searched at the following locations (first match wins):
1. `$XDG_CONFIG_HOME/tod/config`
2. `~/.config/tod/config`
It uses INI format and is written with mode `0600`:```ini
server-url=https://onedev.example.com
access-token=your-personal-access-token
trust-certs-file=/path/to/trust-certs.pem
The ONEDEV_SERVER_URL, ONEDEV_ACCESS_TOKEN, and
ONEDEV_TRUST_CERTS_FILE environment variables override their corresponding
config-file properties.
Quick start```bash
Run CI job against your uncommitted changes
cd /path/to/onedev-git-repository
tod build run --local ci
Run ci job against the main branch
tod build run --branch main ci
Check out pull request PROJ-123 into the current working directory
tod pr checkout PROJ-123
Check out issue PROJ-456 into the current working directory
tod issue checkout PROJ-456
Query open issues assigned to you
tod issue list --query 'assignee is me and state is "Open"'
Inspect the most recent failing build for a project
tod build list --query 'not(successful)' --count 1
tod build get <ref>
tod build get-log <ref>
API commands also work outside a local checkout. Use qualified references for
existing entities and explicit projects when creating issues, pull requests,
or builds:```bash
tod issue get 'myproject#123'
tod issue create 'Fix login' --project myproject
tod issue create-branch 'myproject#123'
tod pr create 'Fix login' --source-project myproject --source-branch issue-123
tod build run ci --project myproject --branch main
Issue, pull request, and build lists query all accessible projects when neither
--project nor a current project inferred from the working directory is
available.
Both checkout commands also move already retrieved submodules to the commits
recorded by the checked out revision, fetching from the remote of the submodule
when a commit is missing locally. Submodules that have not been retrieved stay
untouched; retrieve them with git submodule update --init when needed.
See cli.md for the full command reference.
Agent skills
TOD ships eight tool-agnostic SKILL.md files under skills/ that
teach AI agents how to drive common OneDev workflows through the CLI:
using-tod— perform general OneDev queries and actionsedit-build-spec— author and validate.onedev-buildspec.ymlfix-failed-build— fix a failed build from a prompt-provided build
referencegenerate-commit-message— compose a message that satisfies OneDev
requirementswork-on-issue— check out and implement issue worksubmit-issue-work— submit issue code changes and/or saved comments,
updating or creating a pull request when submitting codework-on-pull-request— review a pull request or implement follow-up worksubmit-pull-request-work— submit code changes and/or saved discussion,
review, and merge actions for an existing pull request
See skills/README.md for how to install these into Claude
Code, Codex, Cursor, or any other agent that reads SKILL.md files.
Notes for local CI runs
Nginx configuration
If OneDev is running behind Nginx, disable HTTP buffering for log streaming:nginx
location /~api/streaming {
proxy_pass http://localhost:6610/~api/streaming;
proxy_buffering off;
}
See the OneDev Nginx setup documentation
for details.
Security considerations
If the job accesses job secrets, make sure the authorization field is cleared
to allow all jobs. Setting authorization to allow all branches is not
sufficient — local changes are pushed to a temporal ref that does not belong
to any branch.
When initialized submodules contain local changes, tod build run --local
collects and sends their snapshots recursively before sending the parent
repository. A submodule that needs to be sent must point to a project on the
configured OneDev server, and the access token must have permission to push to
that project. When the command is started anywhere inside a submodule, it uses
the outermost superproject as its working directory by default. Pass
--working-dir explicitly to run against the submodule itself.
Performance tips
- Large repositories — use an appropriate clone depth in checkout steps
instead of full history. - External dependencies — use
caching for downloads
and intermediate files. - Build optimization — cache slow-to-generate intermediate files.
Contributing
TOD is part of the OneDev ecosystem. For contributions, issues, and feature
requests, visit the OneDev project.
License
See license.txt.
