Common Task Commands

Prefer the committed scripts and workspace tasks over improvised one-off commands.

Daily Entry Points

Backend Commands

Use these when you are changing backend behavior, API contracts, or SMB handling.

cd backend && pytest -v
cd backend && mypy app

Useful related task:

• VS Code task Backend: Run Tests
• VS Code task Backend: Type Check (mypy)

Frontend Commands

Use these when the browser UI, routing, services, or typed frontend behavior changes.

cd frontend && npm test
cd frontend && npx tsc --noEmit
cd frontend && npm run lint

Useful related task:

• VS Code task Frontend: Run Tests
• VS Code task Frontend: Type Check + Lint

Companion Commands

Use these when local-drive access, native-app editing, or Tauri-side behavior changes.

cd companion && npm run lint
cd companion && npx tsc --noEmit
cd companion/src-tauri && cargo test

Useful related task:

• VS Code task Companion: Run Rust Tests
• VS Code task Companion: Type Check + Lint

Local Dev Logs and Service Control

Use the committed helper scripts first when you are diagnosing the supported local development workflow.

Combined Dev Server Control

These scripts manage the local backend and frontend together:

./scripts/dev-start
./scripts/dev-stop
./scripts/dev-stop && ./scripts/dev-start

Use those entry points when you want the repo’s own startup logging and local log-file layout instead of ad hoc process control.

Log Inspection

The supported local log viewer is:

./scripts/logs
./scripts/logs -f
./scripts/logs -n 200

That script summarizes service status and tails the main local development log files.

The current local log files are:

• /tmp/backend.log
• /tmp/frontend.log
• /tmp/dev-start.log
• /tmp/post-start.log

You can inspect individual files directly when needed:

tail -f /tmp/backend.log
tail -f /tmp/frontend.log
tail -f /tmp/dev-start.log
tail -f /tmp/post-start.log

Search and Status Checks

When the helper scripts are not enough, targeted shell checks are still useful.

pgrep -f "uvicorn.*app.main:app"
pgrep -f "vite"
lsof -i :3000,8000
grep -i error /tmp/*.log
grep -i warning /tmp/*.log
grep -i smb /tmp/backend.log
grep -E "\([0-9]{4,}\.[0-9]+ms\)" /tmp/backend.log

Treat these as diagnostics for the local development environment, not as the primary supported control surface.

Be especially careful with broad pkill -f vite-style commands in a workspace that can also run website or companion dev servers.

Rotating and Clearing Local Logs

When local logs become noisy, use the committed rotation script first:

./scripts/rotate-logs

That script archives current /tmp/*.log files into /tmp/logs-archive/ and truncates the live files in place so active writers keep working.

To inspect archived logs:

ls -lh /tmp/logs-archive/

Manual truncation is still possible for local development, but it is a deliberately destructive cleanup step:

> /tmp/backend.log
> /tmp/frontend.log
> /tmp/dev-start.log
> /tmp/post-start.log

Use that only when you intentionally want to discard the current local log history.

Practical Local Triage Order

For the supported dev workflow, a reasonable first pass is:

1. run ./scripts/logs
2. verify the expected dev processes or ports if the summary looks wrong
3. search /tmp/*.log for the concrete failure signal
4. restart with ./scripts/dev-stop && ./scripts/dev-start if the issue is clearly local-process state rather than a code defect

Version Sync

When you change VERSION, run the sync script and review all resulting metadata changes together.

./scripts/sync-version

That workflow updates the frontend and companion package metadata and related version-bearing files.

Command Selection Rule of Thumb

• smallest relevant change: run the checks for the area you changed
• cross-boundary change: run checks for every touched subsystem
• dependency or versioning change: run the affected subsystem checks plus the sync workflow if VERSION changed

For the broader validation strategy and how to choose depth, continue to Test Strategy Overview .