112 lines
4.3 KiB
Markdown
112 lines
4.3 KiB
Markdown
# strea.md
|
|
|
|
|
|
|
|
Strea.md is a personal knowledge management and time-tracking CLI tool. It organizes time-ordered markdown files using `@tag` annotations, letting you manage tasks, track time, and query your notes from the terminal.
|
|
|
|
## Installation
|
|
|
|
### Debian/Ubuntu (.deb package)
|
|
|
|
Download and install the latest release:
|
|
|
|
```bash
|
|
wget https://git.konstantinfickel.de/kfickel/streamd/releases/download/vX.Y.Z/streamd_X.Y.Z_amd64.deb
|
|
sudo dpkg -i streamd_X.Y.Z_amd64.deb
|
|
```
|
|
|
|
This includes shell completions for bash, zsh, and fish.
|
|
|
|
### Static Binary
|
|
|
|
Download the statically-linked binary:
|
|
|
|
```bash
|
|
wget https://git.konstantinfickel.de/kfickel/streamd/releases/download/vX.Y.Z/streamd-X.Y.Z-linux-x86_64
|
|
chmod +x streamd-X.Y.Z-linux-x86_64
|
|
sudo mv streamd-X.Y.Z-linux-x86_64 /usr/local/bin/streamd
|
|
```
|
|
|
|
### Nix
|
|
|
|
Using the flake directly:
|
|
|
|
```bash
|
|
nix run git+https://git.konstantinfickel.de/kfickel/streamd
|
|
```
|
|
|
|
Or add to your NixOS/Home Manager configuration using the provided `homeManagerModules.default`.
|
|
|
|
## Core Concepts
|
|
|
|
- **Shards** — Sections of markdown files, organized hierarchically by headings. Each shard can contain markers, tags, and nested child shards.
|
|
- **Markers** — Special `@tags` like `@Task`, `@Done`, `@Waiting`, or `@Timesheet` that give shards semantic meaning and place them into dimensions.
|
|
- **Dimensions** — Classification axes (e.g. task state, project, timesheet) that categorize shards. Some dimensions propagate to child shards.
|
|
|
|
## File Format
|
|
|
|
Markdown files are named with a timestamp: `YYYYMMDD-HHMMSS [markers].md`
|
|
|
|
For example: `20260131-210000 Task Streamd.md`
|
|
|
|
An optional `_file_type` segment can follow the timestamp to classify the file:
|
|
|
|
```
|
|
YYYYMMDD-HHMMSS_<file_type> [markers].md
|
|
```
|
|
|
|
For example: `20260413-083000_daily.md` — the `daily` prefix is stored as the `file_type` dimension and propagates to all child shards.
|
|
|
|
Within files, `@`-prefixed markers at the beginning of paragraphs or headings define how a shard is categorized.
|
|
|
|
## Commands
|
|
|
|
- `streamd` / `streamd new` — Create a new timestamped markdown entry, opening your editor
|
|
- `streamd daily [YYYYMMDD]` — Open today's daily file (or create it if missing); pass a date to open that day's file instead
|
|
- `streamd todo` — Show all open tasks (shards with `@Task` markers), numbered for easy reference
|
|
- `streamd todo N edit` — Edit task N in your editor, jumping to the task's line
|
|
- `streamd todo N done` — Mark task N as done by inserting `@Done` after `@Task`
|
|
- `streamd todo --show-future` — Include tasks with future dates in the listing
|
|
- `streamd edit [number]` — Edit a stream file by index (most recent first)
|
|
- `streamd timesheet` — Generate time reports from `@Timesheet` markers
|
|
|
|
## Configuration
|
|
|
|
### User Configuration
|
|
|
|
Streamd reads its user configuration from `~/.config/streamd/config.toml` (XDG standard). The main setting is `base_folder`, which points to the directory containing your stream files (defaults to the current working directory).
|
|
|
|
### Repository Configuration
|
|
|
|
For timesheet reporting, create a `.streamd.toml` file in your stream files directory:
|
|
|
|
```toml
|
|
timezone = "Europe/Berlin" # Optional: timezone for day boundaries
|
|
|
|
[timesheet]
|
|
[[timesheet.periods]]
|
|
start = "2026-01-01"
|
|
end = "2026-06-30"
|
|
hours_per_week = 38.0
|
|
|
|
[[timesheet.periods]]
|
|
start = "2026-07-01"
|
|
end = "2026-12-31"
|
|
hours_per_week = 40.0
|
|
```
|
|
|
|
The timesheet command will calculate expected vs actual working hours based on these periods, showing:
|
|
- Daily breakdown with expected/actual hours
|
|
- Special day types (sick leave, vacation, holidays, flex days)
|
|
- Warnings for missing entries and overlapping timecards
|
|
- Monthly and cumulative balance
|
|
|
|
## Usage
|
|
|
|
Running `streamd` opens your editor to create a new entry. After saving, the file is renamed based on its timestamp and any markers found in the content.
|
|
|
|
Running `streamd todo` finds all shards marked as open tasks and displays them numbered in your terminal. Tasks with future dates are hidden by default (use `--show-future` to include them). Tasks are sorted by date with oldest first (task 1 is the oldest).
|
|
|
|
You can quickly edit or complete tasks by number:
|
|
- `streamd todo 1 edit` opens task 1 in your editor at the correct line
|
|
- `streamd todo 1 done` marks task 1 as done by inserting `@Done` after `@Task`
|