---
title: 'Command reference'
url: 'https://chronoslice.app/docs/help/command-reference'
markdown: 'https://chronoslice.app/docs/help/command-reference.md'
date: '2026-11-14'
description: 'The chronoslice program is the server and a set of commands for looking after it. This page lists every command and every flag. Run chronoslice --help, or chronoslice <command> --help, for the same wording at a shell. How to run them chronoslice [--db <url>] <command> [options] -…'
taxonomy:
  kb_category:
    - Help
---

[Docs](https://chronoslice.app/docs)

 [Contact support](https://chronoslice.app/help/new) 

Docs menu

# Command reference

Every chronoslice command and flag, with defaults and examples.

 Updated Nov 14, 2026 8 min read

The `chronoslice` program is the server and a set of commands for looking after it. This page lists every command and every flag. Run `chronoslice --help`, or `chronoslice <command> --help`, for the same wording at a shell.

## How to run them

```text
chronoslice [--db <url>] <command> [options]
```

- **`--db <url>`** works with every command. It's the SQLite database, and defaults to `sqlite://chronoslice.db`. You can set `CHRONOSLICE_DB` instead. With the layout in [Install on Linux](https://chronoslice.app/docs/installing/install-on-linux), the value is `sqlite:///var/lib/chronoslice/chronoslice.db`.
- **`--version`** (or `-V`) prints the version and its release date. **`--help`** (or `-h`) prints help.
- **Settings are read** from your environment, a `.env` file, and `/etc/chronoslice/env`. See [Settings reference](https://chronoslice.app/docs/installing/settings-reference).
- **Running as root or as `chronoslice`.** `sudo chronoslice update` and `sudo chronoslice licence` read `/etc/chronoslice/env` as root. For the other commands that change data, run them as the service's user and name the database:

```sh
sudo -u chronoslice env CHRONOSLICE_DB=sqlite:///var/lib/chronoslice/chronoslice.db chronoslice user set-password you@example.com
```

A command that fails prints `Error:` and a reason, and exits with status 1.

## serve

Run the server: the API, live updates and the web app. You normally run it with systemd. Every flag can be set with the environment variable beside it.

| Flag | Variable | Default | What it does |
|---|---|---|---|
| `--bind <address>` | `CHRONOSLICE_BIND` | `127.0.0.1:7340` | Address to listen on. |
| `--secure-cookies` | `CHRONOSLICE_SECURE_COOKIES` | off | Mark the session cookie Secure. Set it when you serve over HTTPS. As a variable, use `true` or `false`. |
| `--public-url <url>` | `CHRONOSLICE_PUBLIC_URL` | none | The address people reach ChronoSlice at, for links in emails. |
| `--smtp-url <url>` | `CHRONOSLICE_SMTP_URL` | none | Where email goes out: `smtps://user:pass@host:465`, `smtp://user:pass@host:587?tls=required`, or `file:///folder`. |
| `--mail-from <sender>` | `CHRONOSLICE_MAIL_FROM` | none | The sender address, such as `"Your Studio <billing@example.com>"`. Needed with `--smtp-url`. |
| `--setup-token <secret>` | `CHRONOSLICE_SETUP_TOKEN` | none | A secret the first-run setup page asks for. |

## setup

Create the first account and its organization, instead of using the setup page. It refuses if the database already has an account. It reads the password from `CHRONOSLICE_PASSWORD`, or prompts for it, or takes the first line of standard input.

| Flag | Default | What it does |
|---|---|---|
| `--email <email>` | required | Your email, for signing in. |
| `--name <name>` | required | Your name. |
| `--org <name>` | required | The organization's name. |
| `--timezone <zone>` | required | An IANA timezone such as `America/Denver`. |
| `--currency ` | `USD` | A three-letter currency code. |
| `--week-start <day>` | `monday` | A day's name, or `0` (Sunday) to `6` (Saturday). |

## user set-password

```text
chronoslice user set-password <email>
```

Set a user's password. It reads the new password from `CHRONOSLICE_PASSWORD`, or prompts for it, or takes the first line of standard input. The password must be at least 10 characters. It fails if no user has that email.

## token create

```text
chronoslice token create <email> [--name <name>]
```

Create an API token for a user, and print it. `--name` says what the token is for, and defaults to `CLI`. See [API tokens](https://chronoslice.app/docs/using-chronoslice/api-tokens).

## openapi

Print the API's OpenAPI document as JSON. It doesn't touch the database.

## licence

```text
chronoslice licence [activate <key> | check | remove]
```

With no subcommand, it shows where the licence stands: the trial or the edition, active users, the key, updates until, any newer release, the install id and the version. The other subcommands print the same summary when they finish.

| Subcommand | What it does |
|---|---|
| `activate <key>` | Enter a licence key. It takes one of the key's seats for this server. `--label <name>` is what the server is called on your account page. It defaults to its address or host name. |
| `check` | Ask the store about the key now, after renewing or upgrading. |
| `remove` | Take the key off this server and give its seat back, to move it to another server. |

These commands never create a database. They stop with an error if there isn't one at the address you gave. See [Buying and entering a licence](https://chronoslice.app/docs/licence-and-updates/buying-and-entering-a-licence).

## update

Install the newest release the licence covers: download it, check it, back up the database, swap the program and restart the service. Run it as the user that owns the program.

| Flag | Default | What it does |
|---|---|---|
| `--check` | off | Only say whether there's a newer release. |
| `--yes`, `-y` | off | Install without asking. |
| `--no-restart` | off | Don't restart the systemd service afterwards. |
| `--service <name>` | `chronoslice` | The systemd service to restart. |

See [Updating](https://chronoslice.app/docs/licence-and-updates/updating).

## import toggl

Import your Toggl Track workspace: clients, projects, tasks, tags, members, groups, rates and all time entries. It's safe to run again. See [From Toggl Track](https://chronoslice.app/docs/moving-to-chronoslice/from-toggl-track).

| Flag | Variable | What it does |
|---|---|---|
| `--token <token>` | `TOGGL_API_TOKEN` | Your Toggl API token. Required. |
| `--workspace <id>` | none | The workspace id. The default is your token's default workspace. |
| `--from-year <year>` | none | The first year of entries to fetch. The default is the start of the account. |

## import square

Import Square customers, invoices with their payments and fees, and scheduled recurring invoices. Recurring invoices arrive paused. See [From Square](https://chronoslice.app/docs/moving-to-chronoslice/from-square).

| Flag | Variable | What it does |
|---|---|---|
| `--token <token>` | `SQUARE_ACCESS_TOKEN` | A Square access token. Required unless you give `--from`. |
| `--from <folder>` | none | Read a saved export: `customers.json`, `invoices.json`, `orders.json` and `payments.json`. |
| `--save <folder>` | none | Save what was read from Square to this folder, for a later `--from`. |
| `--mapping <file>` | none | A JSON file saying which client each Square customer becomes. |
| `--org <id>` | none | The organization to import into. The default is the only one. |
| `--continue-numbering` | off | Continue invoice numbers after Square's highest plain number. |
| `--skip <numbers>` | none | Invoice numbers to leave in Square, separated by commas. |
| `--dry-run` | off | Show what would happen without keeping anything. |

## import square-attachments

Attach files from Square invoices, from a folder with `manifest.json` and the files in `files/`, after `import square`.

| Flag | What it does |
|---|---|
| `--from <folder>` | The folder with `manifest.json`. Required. |
| `--org <id>` | The organization to import into. The default is the only one. |
| `--dry-run` | Show what would happen without keeping anything. |

It exits with status 1 when there were errors.

## reconcile toggl

Compare an imported Toggl workspace with Toggl's own totals. It takes the same flags as `import toggl`: `--token`, `--workspace` and `--from-year`. It exits with status 1 when something doesn't match. `reconcile` only works for Toggl.

## report pdf

Render a report as a PDF without the server, with your organization's branding.

| Flag | Default | What it does |
|---|---|---|
| `--from <date>` | required | First day, `YYYY-MM-DD`. |
| `--to <date>` | required | Last day, `YYYY-MM-DD`, inclusive. |
| `--out <file>`, `-o` | required | Where to write the PDF. |
| `--org <id>` | none | The organization id. Optional when the database has only one. |
| `--client <name or id>` | none | Limit to a client. Repeat for several. |
| `--member <name or id>` | none | Limit to a member. Repeat for several. |
| `--rounding <rule>` | none | Rounding as `mode:minutes`, such as `up:15`, `nearest:5` or `down:6`. |
| `--round-totals` | off | Round each line and bar of the report instead of each entry. |
| `--group <by>` | `project` | First level of the breakdown: `project`, `client`, `member`, `tag`, `task`, `description` or `day`. |
| `--subgroup <by>` | `description` | Second level: the same choices, or `none`. |
| `--timeline <unit>` | `auto` | Chart buckets: `auto`, `day`, `week` or `month`. |
| `--entries` | off | Add every entry as an appendix. |
| `--landscape` | off | Landscape pages. |
| `--a4` | off | A4 instead of US Letter. |
| `--title <text>` | the client's name | The report's title. |
| `--period-label <text>` | none | The period's name under the title, such as `October 2026`. |
| `--timezone <zone>` | the owner's | An IANA timezone for entry times. |

```sh
sudo -u chronoslice env CHRONOSLICE_DB=sqlite:///var/lib/chronoslice/chronoslice.db \
  chronoslice report pdf --client "Acme" --from 2026-10-01 --to 2026-10-31 \
  --period-label "October 2026" --out /tmp/acme-october.pdf
```

## Imports and the trial

`import` commands are refused while the server is read-only after the trial. See [The trial](https://chronoslice.app/docs/licence-and-updates/the-trial).

## Related

- [Settings reference](https://chronoslice.app/docs/installing/settings-reference)
- [Updating](https://chronoslice.app/docs/licence-and-updates/updating)
- [People and roles](https://chronoslice.app/docs/using-chronoslice/people-and-roles)
- [Reports](https://chronoslice.app/docs/using-chronoslice/reports)

## Still stuck?

Send us a request: it goes to the people who build ChronoSlice, and the reply comes by email. Include your ChronoSlice version (Settings › Licence shows it) and what you tried.

 [Contact support](https://chronoslice.app/help/new?from=%2Fdocs%2Fhelp%2Fcommand-reference)[Your requests](https://chronoslice.app/help/tickets)

---

## Navigation

- Parent: [Help](https://chronoslice.app/docs/help.md)
- Previous: [Troubleshooting](https://chronoslice.app/docs/help/troubleshooting.md)
