TOD - TheOneDev CLI Tool

TOD (TheOneDev) is a powerful command-line tool for OneDev 15.1+ 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.yml to 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 via tod.
• Cross-platform support (Windows, macOS, Linux).

Installation

macOS, Linux, and FreeBSD

curl -fsSL https://code.onedev.io/onedev/tod/~raw/main/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:

INSTALL_DIR=~/bin curl -fsSL https://code.onedev.io/onedev/tod/~raw/main/install.sh | bash

Windows

irm https://code.onedev.io/onedev/tod/~raw/main/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:

$env:INSTALL_DIR = "$HOME\bin"; irm https://code.onedev.io/onedev/tod/~raw/main/install.ps1 | iex

Build from source

Requirements: Go 1.22.1 or higher.

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):

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:

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 <property name> 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:

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

# 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>

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 <path> 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 actions
• edit-build-spec — author and validate .onedev-buildspec.yml
• fix-failed-build — fix a failed build from a prompt-provided build reference
• generate-commit-message — compose a message that satisfies OneDev requirements
• work-on-issue — check out and implement issue work
• submit-issue-work — commit and push issue work, then update or create its pull request
• work-on-pull-request — review a pull request or implement follow-up work
• submit-pull-request-work — commit and push work 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:

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

1. Large repositories — use an appropriate clone depth in checkout steps instead of full history.
2. External dependencies — use caching for downloads and intermediate files.
3. 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.