# Using One Track as an Agent

> The web app at [/app](https://one-track.app/app) is a WASM SPA built for humans; agents get the same tracks, entries, and dependency graph through the `one_track` CLI.

## Install

POSIX (macOS, Linux):

```sh
curl -fsSL https://one-track.app/install.sh | sh
```

Windows (PowerShell):

```powershell
irm https://one-track.app/install.ps1 | iex
```

Full install page: [one-track.app/cli?format=md](https://one-track.app/cli?format=md).

## Authenticate

Device authorization plus end-to-end-encryption unlock, in one step:

```sh
one_track login
```

What happens, from your side:

1. The CLI prints a verification code and a link of the form `https://one-track.app/activate?code=…`, then polls in the foreground.
2. A signed-in human opens that link in a browser, checks the code and device name, and approves — choosing a role and expiry for the grant. Relay the code and URL to your human; the request expires after 15 minutes.
3. On approval the CLI receives an `ot_live_…` token (delivered exactly once) and saves it locally.
4. The CLI then unlocks the account's end-to-end-encrypted data: it prompts for the encryption passphrase, or reads it non-interactively from `--passphrase-file FILE` or `$ONE_TRACK_PASSPHRASE`. On a brand-new account this step sets the passphrase instead. Once unlocked, data commands read and write the same encrypted document the web app shows.

Options: `--device-name NAME` (or `$ONE_TRACK_DEVICE_NAME`) labels the request on the approval page; `--url` (or `$ONE_TRACK_URL`) targets a non-default server.

Alternative sign-in with an emailed one-time code (no browser approval needed, and required later for `github link`):

```sh
one_track login you@example.com
one_track login you@example.com --code 123456
```

Alternative for pre-issued role-scoped tokens: pass `--token TOKEN` (or set `$ONE_TRACK_TOKEN`) on any command. Note the trade-off: an explicit token session operates on the published plaintext dataset, not the encrypted document, so it only sees tracks that have been published.

Session management:

```sh
one_track whoami
one_track logout
```

Every command accepts the global `--json` flag for machine-readable output and `--yes` to apply one-way-door changes without the interactive confirmation.

## Connect over MCP

An MCP server (`one_track mcp`) is in development but not part of the released CLI yet. Until it ships, invoke `one_track` directly — every command accepts `--json` for machine-readable output.

## Manage tasks

Entries (tasks) belong to tracks (projects) and form a directed acyclic dependency graph. Anywhere a command takes a track or entry, you may pass a UUID, a UUID prefix, or the title.

Tracks:

```sh
one_track track list
one_track track add "Launch prep" --description "Everything before the announcement"
one_track track edit "Launch prep" --title "Launch"
one_track track rm "Launch" --force
```

`track rm` refuses to delete a track that still has entries unless you pass `--force` (which deletes them too).

Read the dashboard and individual entries:

```sh
one_track list
one_track list --track "Launch" --active
one_track list --completed
one_track show "write announcement"
```

`show` prints one entry in full, including its dependencies.

Create entries, optionally wired into the dependency graph at birth:

```sh
one_track add "write announcement" --track "Launch"
one_track add "publish announcement" --description "after review" --parent "write announcement"
one_track add "draft outline" --child "write announcement"
```

`--parent` names an entry this one depends on; `--child` names an entry that depends on this one. Both are repeatable. Without `--track`, the entry lands in the active track.

Complete, reopen, edit, delete:

```sh
one_track done "write announcement"
one_track reopen "write announcement"
one_track edit "write announcement" --title "write launch post" --description "800 words" --track "Launch"
one_track rm "draft outline"
```

Rewire dependencies after the fact — `link PARENT CHILD` makes CHILD depend on PARENT:

```sh
one_track link "write announcement" "publish announcement"
one_track unlink "write announcement" "publish announcement"
```

## Share and publish

Sharing and visibility commands take UUIDs (get them from `one_track list --json` or `one_track org show`). Sharing rides on Pro; the plan itself is CLI-manageable:

```sh
one_track account
one_track upgrade
one_track downgrade
```

Share a single track with another account by email (`--level view` is the default; on an unlocked device the CLI publishes the track's current encrypted content first, so the recipient sees what you see):

```sh
one_track share invite TRACK_UUID them@example.com --level edit
one_track share list TRACK_UUID
one_track share set-level TRACK_UUID SHARE_UUID view
one_track share revoke TRACK_UUID SHARE_UUID
one_track share accept INVITE_TOKEN
```

The invite lands in the recipient's email; they accept with `share accept` or in the web app.

Track visibility inside an organization (`private`, `by_role`, `org`, or `public`, bounded by your role's grants):

```sh
one_track visibility get TRACK_UUID
one_track visibility set TRACK_UUID org --org ORG_UUID
one_track visibility set TRACK_UUID by_role --org ORG_UUID --roles ROLE_UUID,ROLE_UUID
```

Organization administration:

```sh
one_track org create "Acme"
one_track org list
one_track org show ORG_UUID
one_track org member add ORG_UUID them@example.com --role ROLE_UUID
one_track org member set-role ORG_UUID USER_UUID ROLE_UUID
one_track org member remove ORG_UUID USER_UUID
one_track org role create ORG_UUID "Reviewer"
one_track org role edit ORG_UUID ROLE_UUID --grant org=yes,private=no,by_role=no,public=no --caps assign_roles=yes,edit_shared_tracks=no
one_track org role delete ORG_UUID ROLE_UUID
one_track org audit ORG_UUID
one_track org risks ORG_UUID
one_track org cli ORG_UUID off
```

Destructive or hard-to-reverse changes (the "one-way door") prompt for confirmation; pass `--yes` to acknowledge non-interactively.

Still needs a human in the web app:

- Approving a device-authorization request, choosing its role and expiry: [one-track.app/activate](https://one-track.app/activate).
- Passkeys, recovery codes, and changing the encryption passphrase: managed in the web app at [one-track.app/app](https://one-track.app/app).

## GitHub integration

Links a One Track entry to a GitHub issue so that closing the issue fires a blinded webhook trigger, which launches a Claude agent that completes the entry, marks follow-up entries in progress, and starts the follow-up work. The server never learns which repo, issue, or entry a trigger watches.

```sh
one_track github link --repo owner/name --issue 203 --entry "ship docs" --follow-up 204="deploy docs" --claude-trigger-id TRIGGER_ID --mode live
one_track github dispatch --help
one_track github status
one_track github fire
one_track github relink --fingerprint HEX --renew
one_track github unlink --fingerprint HEX --revoke-grant GRANT_UUID
```

One-time setup needs human steps: sign in with an email-code login (`one_track login you@example.com` — device-grant tokens cannot bind identity keys), install the One Track GitHub App on the repository (or configure a repo webhook to `https://one-track.app/hooks/github`), create the claude.ai routine and its run token, and put the values `github link` prints into the agent environment's secrets. Inside that environment, `one_track agent process --json` pulls deliveries, applies them to the encrypted state, and acks; `one_track agent complete ENTRY` finishes an entry and fires the dispatch trigger for newly-ready work.

## More

- [one-track.app/llms.txt](https://one-track.app/llms.txt)
- [one-track.app/security?format=md](https://one-track.app/security?format=md)
- [one-track.app/pricing?format=md](https://one-track.app/pricing?format=md)