# TOD - TheOneDev CLI Tool

TOD (**T**he**O**ne**D**ev) 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/`](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

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

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

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](cli.md) for the full command reference.

## Agent skills

TOD ships eight tool-agnostic `SKILL.md` files under [`skills/`](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](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](https://docs.onedev.io/administration-guide/reverse-proxy-setup#nginx)
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](https://docs.onedev.io/tutorials/cicd/job-cache) 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](https://code.onedev.io/onedev/tod).

## License

See [license.txt](license.txt).