Command reference
Every chronoslice command and flag, with defaults and examples.
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]
--db <url>works with every command. It's the SQLite database, and defaults tosqlite://chronoslice.db. You can setCHRONOSLICE_DBinstead. With the layout in Install on Linux, the value issqlite:///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
.envfile, and/etc/chronoslice/env. See Settings reference. - Running as root or as
chronoslice.sudo chronoslice updateandsudo chronoslice licenceread/etc/chronoslice/envas root. For the other commands that change data, run them as the service's user and name the database:
sudo -u chronoslice env CHRONOSLICE_DB=sqlite:///var/lib/chronoslice/chronoslice.db chronoslice user set-password [email protected]
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 <[email protected]>". 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 <code> |
USD |
A three-letter currency code. |
--week-start <day> |
monday |
A day's name, or 0 (Sunday) to 6 (Saturday). |
user set-password
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
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.
openapi
Print the API's OpenAPI document as JSON. It doesn't touch the database.
licence
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.
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.
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.
| 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.
| 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. |
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.
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.