Remote support

A convenient command that comes with the standard todu plugin is todu branch <id> <branch-name>, which will associate a todo item with a specific branch, create the branch if it doesn't exist, and switch to it.

All other remote commands require todu to be built with --features remote.

Configuring Remote

Remotes are configured per-project but credentials are never stored in the database — they are read from a token file or the OS keychain at runtime. To configure token files you can add the following to your config:

$env.config.plugins.todu = {
    github: {
        token_file: "~/.config/todu/github_token"  # file containing a GitHub PAT with read/write issues permissions
    }
    jira: {
        email:      "me@example.com"
        token_file: "~/.config/todu/jira_token"    # file containing a Jira API token
    }
}

Note: token files should contain only the token string

Alternatively, omit token_file from the config and store tokens in the OS keychain:

Remote	Service	Account
GitHub	todu-github	{owner}/{repo}
Jira	todu-jira	{email}

# macOS
security add-generic-password -s todu-github -a myorg/myrepo -w "ghp_xxxx"
security add-generic-password -s todu-jira   -a me@example.com -w "xxxx"

# Linux (secret-service)
secret-tool store --label='todu github' service todu-github account myorg/myrepo
secret-tool store --label='todu jira'   service todu-jira   account me@example.com

Note: Linux keychain support requires a running Secret Service (GNOME Keyring or KWallet). Use token_file in headless environments.

Then, to register a remote source to a project:

cd ~/dev/myproject
todu remote add github https://github.com/myorg/myrepo
todu remote add jira https://myorg.atlassian.net/PROJ

The Jira project key is required as a path segment in the URL. Pulls are scoped to that project.

Pull

todu pull github   # imports open issues from all GitHub remotes
todu pull jira     # imports assigned, non-done issues from all Jira remotes

Status changes are pushed back automatically. When you run any status command on a remote-sourced todo, todu updates the remote in the same operation — no separate sync step needed:

todu done 3     # closes the GitHub issue (reason: completed) / transitions Jira to Done
todu stop 3     # closes the GitHub issue (reason: not_planned) / transitions Jira to Done
todu start 4    # reopens the GitHub issue / transitions Jira to In Progress
todu reopen 5   # reopens the GitHub issue / transitions Jira to To Do

For Jira, todu matches transitions by status category rather than by name, so it works regardless of how your board's workflow is named:

todu status	Jira category
done, stop	Done
start, in-review	In Progress
pending, pause	To Do

The tag column holds the issue identifier (#42 for GitHub, PROJ-123 for Jira) and is read-only on remote todos.

Note: As of right now, todu only supports pulling already created remote issues and does not support pushing locally created items to remote.