Metadata-Version: 2.4
Name: freeagent-cli
Version: 0.2.1
Summary: CLI for submitting FreeAgent timeslips
Project-URL: Homepage, https://github.com/tomdyson/freeagent-cli
Project-URL: Repository, https://github.com/tomdyson/freeagent-cli
Project-URL: Issues, https://github.com/tomdyson/freeagent-cli/issues
Author-email: Tom Dyson <tom@naive.co.uk>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,freeagent,timeslip,timetracking
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.0
Description-Content-Type: text/markdown

# freeagent-cli

A small CLI for submitting FreeAgent timeslips without clicking through the web UI.

```
freeagent-cli log acme 1h30m "fixed the thing"
```

## Install

```
uv tool install freeagent-cli
```

## One-time setup

You'll need to register your own OAuth app with FreeAgent. It takes about two minutes and keeps your data and rate limits separate from everyone else's.

1. Go to <https://dev.freeagent.com/apps> and create a new app.
2. Set the redirect URI to: `http://localhost:7878/callback`
3. Note the **OAuth identifier** and **OAuth secret**.
4. Save them locally:

   ```
   freeagent-cli auth init --client-id <id> --client-secret <secret>
   ```

   Add `--sandbox` if you want to test against the FreeAgent sandbox first.
5. Authorise the app in your browser:

   ```
   freeagent-cli auth login
   ```

   A browser tab opens, you approve, and the CLI captures the refresh token. The refresh token lasts ~20 years; access tokens auto-refresh on every command.

Credentials are stored at `~/Library/Application Support/freeagent-cli/config.json` (macOS) or the equivalent platform config directory, with file mode `0600`.

## Usage

```
freeagent-cli --help                                       # canonical flow
freeagent-cli projects                                     # projects + tasks in one call
freeagent-cli log <project> <duration> [comment...]        # submit a timeslip
freeagent-cli recent                                       # last few timeslips
```

Examples:

```
freeagent-cli log Acme 1h30m "fixed the thing"
freeagent-cli log Acme 90m fixed the thing                 # comment without quotes
freeagent-cli log "Big Co" 1.5 --task Coding --date 2026-05-01
freeagent-cli log Acme 1.5 --dry-run                       # preview, don't submit
```

- **Duration** accepts `1.5`, `90m`, `1h30m`, or `1:30`.
- **Project / task** match by case-insensitive name substring, numeric id, or full URL.
- **`--task`** is optional when the project has a single task; otherwise the error lists the choices.
- **`--date`** defaults to today (ISO `YYYY-MM-DD` to override).
- **`--dry-run`** resolves the project/task/date and prints the would-be submission without sending it.
- **`projects --flat`** emits one project/task pair per line (tab-separated) for grep/awk.

## License

MIT
