# Timely on boxd

> Timely is an automatic time-tracking platform capturing activity across applications, calendars, and devices, creating detailed timesheets for billing or productivity insights.

- Page: https://boxd.sh/integrations/timely/
- CLI: `run timely` (41 commands, 25 marked common)
- SDK: `import { timely } from "@boxd/run"`; every parameter and response type is at `@boxd/run/timely`
- Triggers: none
- Connect: `run auth timely` (Sign in with Timely), or https://app.boxd.sh/integrations/detail/timely
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth timely      # once: prints a link to connect your account
run timely           # list its commands
run timely list-teams
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { every, timely } from "@boxd/run";

every("1 hour", async () => {
  const result = await timely.listTeams({});
  console.log(result);
});
```

Run it with `run timely.run.ts`. Timely has no triggers; `every()` polls on a schedule, keeps the script running as a job, and wakes the machine when it is due.

## Commands

Required flags are listed; `run timely <command> --help` lists the optional ones. "common" marks what `run timely` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `create-client` | `timely.createClient()` | `--name` | 4 | Create a new client in the specified Timely account |
| `create-day-locking` ·common | `timely.createDayLocking()` | `--day-property` | 1 | Create a day locking entry that prevents editing of time entries for specific dates and users |
| `create-label` | `timely.createLabel()` | `--name` | 4 | Create a new label in the specified Timely account |
| `create-report` ·common | `timely.createReport()` | — | 5 | Generate reports for a Timely account with optional filters |
| `create-team` ·common | `timely.createTeam()` | `--color` `--name` | 2 | Create a new team in the specified Timely account |
| `create-webhook` ·common | `timely.createWebhook()` | `--subscriptions` `--url` | 2 | Create a new webhook for the specified account |
| `delete-label` | `timely.deleteLabel()` | `--account-id` `--id` | 0 | Delete a label by ID from a Timely account |
| `delete-team` | `timely.deleteTeam()` | `--id` | 1 | Delete a team by its ID |
| `delete-webhook` ·common | `timely.deleteWebhook()` | `--id` | 1 | Delete an existing webhook by its ID |
| `filter-reports` ·common | `timely.filterReports()` | — | 8 | Filter Timely reports based on date range, users, projects, labels, teams, and billing status |
| `get-activities` ·common | `timely.getActivities()` | — | 1 | Retrieve all activities (audit trail) for a Timely account |
| `get-client` | `timely.getClient()` | `--id` | 1 | Retrieve details of a specific client by its ID |
| `get-current-permissions` ·common | `timely.getCurrentPermissions()` | `--account-id` | 0 | Retrieve the current user's permissions for a specified account |
| `get-current-user` ·common | `timely.getCurrentUser()` | `--account-id` | 0 | Retrieve the currently authenticated user |
| `get-label` ·common | `timely.getLabel()` | `--account-id` `--id` | 0 | Retrieve a label by ID from a Timely account |
| `get-project` ·common | `timely.getProject()` | `--account-id` `--id` | 0 | Retrieve a single project by its ID |
| `get-team` | `timely.getTeam()` | `--id` | 1 | Retrieve details of a specific team by its ID |
| `get-user` ·common | `timely.getUser()` | `--account-id` `--id` | 0 | Retrieve a user by ID from a Timely account |
| `get-user-capacities` | `timely.getUserCapacities()` | `--account-id` `--user-id` | 0 | Retrieve capacity information for a specific user in a Timely account |
| `get-user-permissions` ·common | `timely.getUserPermissions()` | `--account-id` `--user-id` | 0 | Retrieve a user's permissions by their ID |
| `get-webhook` | `timely.getWebhook()` | `--id` | 1 | Retrieve a specific webhook by its ID |
| `list-accounts` | `timely.listAccounts()` | — | 0 | Retrieve all accessible Timely accounts for the authenticated user |
| `list-clients` ·common | `timely.listClients()` | — | 5 | List all clients in a Timely account with optional filtering and sorting |
| `list-events` ·common | `timely.listEvents()` | — | 7 | List all events (time entries) in a Timely account with optional filtering by date range, users, and projects |
| `list-forecasts` | `timely.listForecasts()` | — | 3 | List all forecasts (tasks) in a Timely account with optional date filtering |
| `list-labels` | `timely.listLabels()` | — | 4 | List all labels in a Timely account |
| `list-project-events` ·common | `timely.listProjectEvents()` | `--account-id` `--project-id` | 0 | List all events (time entries) for a specific project in Timely |
| `list-projects` ·common | `timely.listProjects()` | — | 11 | List all projects in a Timely account with optional filtering and sorting |
| `list-roles` | `timely.listRoles()` | `--account-id` | 0 | List all available roles in a Timely account |
| `list-teams` ·common | `timely.listTeams()` | — | 1 | List all teams in the specified Timely account |
| `list-user-events` ·common | `timely.listUserEvents()` | `--user-id` | 1 | List all events (time entries) for a specific user in Timely |
| `list-users` ·common | `timely.listUsers()` | `--account-id` | 3 | List all users in a Timely account with optional filtering and pagination |
| `list-webhooks` | `timely.listWebhooks()` | — | 1 | List all webhooks in the specified account |
| `process-bulk-events` ·common | `timely.processBulkEvents()` | `--account-id` | 3 | Create, update, or delete multiple events in a single bulk operation |
| `retrieve-account` ·common | `timely.retrieveAccount()` | `--id` | 0 | Retrieve details of a specific account by its ID |
| `update-client` | `timely.updateClient()` | `--client` `--id` | 1 | Update an existing client by ID in Timely |
| `update-day-locking` | `timely.updateDayLocking()` | `--day-property` | 1 | Update day locking settings for specified users and dates |
| `update-label` | `timely.updateLabel()` | `--account-id` `--id` `--label` | 0 | Update a label by ID in a Timely account |
| `update-project` ·common | `timely.updateProject()` | `--account-id` `--id` `--project` | 0 | Update a project by ID in a Timely account |
| `update-user` ·common | `timely.updateUser()` | `--account-id` `--id` `--user` | 0 | Update a user by ID in a Timely account |
| `update-webhook` ·common | `timely.updateWebhook()` | `--account-id` `--id` | 5 | Update an existing webhook by ID |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.