CLI Reference

Complete guide to all ShellTime CLI commands

$ shelltime init

Getting Started

shelltime init

Initialize shelltime: authenticate, install hooks, start daemon, and configure AI code integrations. This is the recommended way to set up shelltime after installation.

--token, -tAuthentication token (skip browser auth)

shelltime init

shelltime auth

Authenticate with shelltime.xyz. Opens a browser for login, or accepts a token directly.

--token, -tAuthentication token (skip browser auth)

shelltime doctor

Diagnose your shelltime setup. Checks system info, config validity, daemon status, and hook installation.

shelltime doctor

Command Tracking

shelltime trackinternal

Track user commands. This is called automatically by installed shell hooks — you do not need to run this manually.

--shell, -sShell type

--sessionId, --idUnix timestamp of the session

--command, --cmdCommand that was executed

--phase, -pPhase: pre or post

--result, -rExit code of last command

--ppidParent process ID of the shell (for terminal detection)

shelltime sync

Manually sync locally stored commands to the server. Useful if the daemon was offline or you want to force an immediate sync.

--dry-run, -drPreview what would be synced without sending

shelltime sync --dry-run

shelltime ls

List commands saved in local storage.

--format, -fOutput format: table or json (default: table)

shelltime ls --format json

shelltime gc

Clean internal storage to free up disk space.

--withLog, -wlAlso clean the log file

--skipLogCreation, -slcSkip creating a new log file after cleanup

Search & AI

shelltime queryalias: q

Ask AI for command suggestions based on a natural language prompt.

shelltime query "find all files modified in the last 24 hours"
shelltime q "show disk usage for current directory"

shelltime rgalias: grep

Search your server-synced command history with powerful filters.

--format, -fOutput format: table or json (default: table)

--limit, -lMaximum number of results (default: 50)

--last-idStart after this command ID (for pagination)

--shell, -sFilter by shell (bash, zsh, fish)

--hostname, -HFilter by hostname

--username, -uFilter by username

--result, -rFilter by exit code (-1 means any)

--main-command, -mFilter by main command (e.g., git, npm)

--sinceFilter commands since date (2024, 2024-01, or 2024-01-15)

--untilFilter commands until date (2024, 2024-01, or 2024-01-15)

shelltime rg "docker" --shell zsh --since 2024-01
shelltime grep "git push" --main-command git --limit 10

Shell Management

shelltime hooks

Manage shelltime shell hooks. Hooks are what enable automatic command tracking in your shell.

shelltime hooks install

Install shelltime hooks into your shell configuration files.

shelltime hooks uninstall

Remove shelltime hooks from your shell configuration files.

shelltime alias

Manage shell aliases. Import aliases from your shell configuration files to sync them with shelltime.

shelltime alias import

Import aliases from shell configuration files.

--fully-refresh, --fullFully refresh all aliases instead of incremental import

--fish-config, -fcFish config file path (default: ~/.config/fish/config.fish)

--zsh-config, -zcZsh config file path (default: ~/.zshrc)

shelltime dotfiles

Sync your dotfiles across machines. Supports nvim, fish, git, zsh, bash, ghostty, claude, starship, npm, ssh, kitty, and kubernetes configurations.

shelltime dotfiles push

Push local dotfiles to the server.

--apps, -aSpecify which apps to push (e.g., nvim,fish,git). If empty, pushes all

shelltime dotfiles pull

Pull dotfiles from the server and save to local config.

--apps, -aSpecify which apps to pull. If empty, pulls all

--dry-run, -nShow what would be changed without writing files

Daemon

shelltime daemon

Manage the shelltime background daemon. The daemon handles syncing commands to the server automatically.

shelltime daemon status

Check the status of the shelltime daemon service.

shelltime daemon install

Install the shelltime daemon service.

shelltime daemon uninstall

Uninstall the shelltime daemon service.

shelltime daemon reinstall

Reinstall the daemon service (uninstall then install).

AI Integrations

shelltime cc

Claude Code integration. Configure OpenTelemetry environment variables for tracking Claude Code usage.

shelltime cc installalias: -i

Install Claude Code OTEL environment configuration to shell config files.

shelltime cc uninstallalias: -u

Remove Claude Code OTEL environment configuration from shell config files.

shelltime cc statusline

Output statusline for Claude Code (reads JSON from stdin).

shelltime codex

OpenAI Codex integration. Configure OTEL settings in Codex config for tracking usage.

shelltime codex installalias: -i

Install Codex OTEL configuration to ~/.codex/config.toml.

shelltime codex uninstallalias: -u

Remove ShellTime OTEL configuration from ~/.codex/config.toml.

Configuration

shelltime config

Manage shelltime configuration.

shelltime config view

View current configuration.

--format, -fOutput format: table or json (default: table)

shelltime schema

Generate JSON schema for the config file. Useful for IDE autocompletion and validation.

--output, -oOutput file path (default: stdout)

shelltime schema --output ~/.config/shelltime/schema.json

shelltime web

Open the ShellTime web dashboard in your default browser.

Global Flags

These flags can be used with any command.

--version, -vPrint the version

--help, -hShow help for any command

Ready to get started?

Install the CLI and run shelltime init to set everything up.

CLI Reference

Complete guide to all ShellTime CLI commands

$ shelltime init

Getting Started

shelltime init

Initialize shelltime: authenticate, install hooks, start daemon, and configure AI code integrations. This is the recommended way to set up shelltime after installation.

--token, -tAuthentication token (skip browser auth)

shelltime init

shelltime auth

Authenticate with shelltime.xyz. Opens a browser for login, or accepts a token directly.

--token, -tAuthentication token (skip browser auth)

shelltime doctor

Diagnose your shelltime setup. Checks system info, config validity, daemon status, and hook installation.

shelltime doctor

Command Tracking

shelltime trackinternal

Track user commands. This is called automatically by installed shell hooks — you do not need to run this manually.

--shell, -sShell type

--sessionId, --idUnix timestamp of the session

--command, --cmdCommand that was executed

--phase, -pPhase: pre or post

--result, -rExit code of last command

--ppidParent process ID of the shell (for terminal detection)

shelltime sync

Manually sync locally stored commands to the server. Useful if the daemon was offline or you want to force an immediate sync.

--dry-run, -drPreview what would be synced without sending

shelltime sync --dry-run

shelltime ls

List commands saved in local storage.

--format, -fOutput format: table or json (default: table)

shelltime ls --format json

shelltime gc

Clean internal storage to free up disk space.

--withLog, -wlAlso clean the log file

--skipLogCreation, -slcSkip creating a new log file after cleanup

Search & AI

shelltime queryalias: q

Ask AI for command suggestions based on a natural language prompt.

shelltime query "find all files modified in the last 24 hours"
shelltime q "show disk usage for current directory"

shelltime rgalias: grep

Search your server-synced command history with powerful filters.

--format, -fOutput format: table or json (default: table)

--limit, -lMaximum number of results (default: 50)

--last-idStart after this command ID (for pagination)

--shell, -sFilter by shell (bash, zsh, fish)

--hostname, -HFilter by hostname

--username, -uFilter by username

--result, -rFilter by exit code (-1 means any)

--main-command, -mFilter by main command (e.g., git, npm)

--sinceFilter commands since date (2024, 2024-01, or 2024-01-15)

--untilFilter commands until date (2024, 2024-01, or 2024-01-15)

shelltime rg "docker" --shell zsh --since 2024-01
shelltime grep "git push" --main-command git --limit 10

Shell Management

shelltime hooks

Manage shelltime shell hooks. Hooks are what enable automatic command tracking in your shell.

shelltime hooks install

Install shelltime hooks into your shell configuration files.

shelltime hooks uninstall

Remove shelltime hooks from your shell configuration files.

shelltime alias

Manage shell aliases. Import aliases from your shell configuration files to sync them with shelltime.

shelltime alias import

Import aliases from shell configuration files.

--fully-refresh, --fullFully refresh all aliases instead of incremental import

--fish-config, -fcFish config file path (default: ~/.config/fish/config.fish)

--zsh-config, -zcZsh config file path (default: ~/.zshrc)

shelltime dotfiles

Sync your dotfiles across machines. Supports nvim, fish, git, zsh, bash, ghostty, claude, starship, npm, ssh, kitty, and kubernetes configurations.

shelltime dotfiles push

Push local dotfiles to the server.

--apps, -aSpecify which apps to push (e.g., nvim,fish,git). If empty, pushes all

shelltime dotfiles pull

Pull dotfiles from the server and save to local config.

--apps, -aSpecify which apps to pull. If empty, pulls all

--dry-run, -nShow what would be changed without writing files

Daemon

shelltime daemon

Manage the shelltime background daemon. The daemon handles syncing commands to the server automatically.

shelltime daemon status

Check the status of the shelltime daemon service.

shelltime daemon install

Install the shelltime daemon service.

shelltime daemon uninstall

Uninstall the shelltime daemon service.

shelltime daemon reinstall

Reinstall the daemon service (uninstall then install).

AI Integrations

shelltime cc

Claude Code integration. Configure OpenTelemetry environment variables for tracking Claude Code usage.

shelltime cc installalias: -i

Install Claude Code OTEL environment configuration to shell config files.

shelltime cc uninstallalias: -u

Remove Claude Code OTEL environment configuration from shell config files.

shelltime cc statusline

Output statusline for Claude Code (reads JSON from stdin).

shelltime codex

OpenAI Codex integration. Configure OTEL settings in Codex config for tracking usage.

shelltime codex installalias: -i

Install Codex OTEL configuration to ~/.codex/config.toml.

shelltime codex uninstallalias: -u

Remove ShellTime OTEL configuration from ~/.codex/config.toml.

Configuration

shelltime config

Manage shelltime configuration.

shelltime config view

View current configuration.

--format, -fOutput format: table or json (default: table)

shelltime schema

Generate JSON schema for the config file. Useful for IDE autocompletion and validation.

--output, -oOutput file path (default: stdout)

shelltime schema --output ~/.config/shelltime/schema.json

shelltime web

Open the ShellTime web dashboard in your default browser.

Global Flags

These flags can be used with any command.

--version, -vPrint the version

--help, -hShow help for any command

Ready to get started?

Install the CLI and run shelltime init to set everything up.