Docs Contact support
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

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, 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.
  • 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:
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.

Was this helpful?

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.