Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/devv-shayan/Trueears/llms.txt

Use this file to discover all available pages before exploring further.

Log Mode lets users dictate timestamped bullet points directly into a text file — useful for journaling, work logs, or any running note document. Each app profile can have its own log file path.

​
TypeScript interface

interface PathValidation {
  valid: boolean;           // Whether the path can be used as a log destination
  exists: boolean;          // Whether the file already exists on disk
  parent_exists: boolean;   // Whether the parent directory exists
  writable: boolean;        // Whether the file/directory is writable
  error_message: string | null; // Human-readable reason if not writable
}
Log files can use .md, .txt, or .log extensions. All paths must be absolute and must not contain path traversal sequences (..).

​
append_to_file

Appends content to the specified file. If the file does not exist it is created. If the parent directory does not exist, it is created recursively. The frontend is responsible for formatting the timestamp and bullet prefix before calling this command. 
import { invoke } from '@tauri-apps/api/core';

const timestamp = new Date().toLocaleString('sv').slice(0, 16).replace('T', ' ');
const entry = `- [${timestamp}] Fix the authentication bug`;

await invoke('append_to_file', {
  path: 'C:/Users/name/Documents/Trueears/vscode-log.md',
  content: entry
});
// Appends: "- [2026-03-25 14:30] Fix the authentication bug\n"

​
Parameters

​
path
string
required
Absolute path to the log file. Must use a .md, .txt, or .log extension. The file and any missing parent directories are created automatically.
​
content
string
required
The full line to append, including any timestamp or bullet formatting. A newline is added automatically after the content.

​
Returns

Promise<void>

​
Error codes

The command rejects with a string error code prefix on failure:
Error codeMeaning
INVALID_PATHPath is not absolute or contains traversal sequences
INVALID_EXTENSIONFile extension is not .md, .txt, or .log
PERMISSION_DENIEDCannot write to the file
DISK_FULLInsufficient disk space
FILE_LOCKEDFile is in use by another process (Windows)
IO_ERROROther I/O failure

​
validate_log_path

Validates a file path before using it as a log destination. Use this to give the user immediate feedback when they type a path in the settings UI. 
import { invoke } from '@tauri-apps/api/core';

const result = await invoke<PathValidation>('validate_log_path', {
  path: 'C:/Users/name/Documents/Trueears/notes.md'
});

if (result.valid) {
  console.log('Path is ready to use');
  if (!result.exists) {
    console.log('File will be created on first log entry');
  }
} else {
  console.error('Invalid path:', result.error_message);
}

​
Parameters

​
path
string
required
The absolute file path to validate. Must use a .md, .txt, or .log extension.

​
Returns

Promise<PathValidation>
​
valid
boolean
true if the path can be used as a log file destination.
​
exists
boolean
true if a file already exists at this path.
​
parent_exists
boolean
true if the parent directory exists. If false, append_to_file will attempt to create it.
​
writable
boolean
true if the file or parent directory is writable by the current user.
​
error_message
string | null
A human-readable explanation of why the path is not writable, or null if it is valid.

​
Validation checks

  1. Path must be absolute (no relative paths).
  2. Path must not contain traversal sequences (.., ./, .\\).
  3. File extension must be .md, .txt, or .log.
  4. The file or parent directory must be writable (if parent does not exist, it is assumed creatable).

​
get_default_log_directory

Returns the default directory where Trueears stores log files. Use this to pre-fill the path input in the settings UI. 
import { invoke } from '@tauri-apps/api/core';

const dir = await invoke<string>('get_default_log_directory');
console.log(dir);
// Windows: "C:\Users\name\Documents\Trueears"
// macOS:   "/Users/name/Documents/Trueears"
// Linux:   "/home/name/Documents/Trueears"

​
Returns

Promise<string> — An absolute path to the default log directory (<Documents>/Trueears). The directory may not exist yet — it is created when the first log entry is appended.

​
open_log_file

Opens the specified log file using the default application associated with its extension on the user’s system. 
import { invoke } from '@tauri-apps/api/core';

await invoke('open_log_file', {
  path: 'C:/Users/name/Documents/Trueears/vscode-log.md'
});

​
Parameters

​
path
string
required
Absolute path to the file to open. The file must already exist.

​
Returns

Promise<void> — Rejects with FILE_NOT_FOUND if the file does not exist, or OPEN_FAILED if the OS fails to open it.

​
Full log mode example

import { invoke } from '@tauri-apps/api/core';

async function setupLogMode(userPath: string | null): Promise<string> {
  // If no path configured, build one from the default directory
  const dir = await invoke<string>('get_default_log_directory');
  const logPath = userPath ?? `${dir}/notes.md`;

  // Validate before saving to settings
  const validation = await invoke<PathValidation>('validate_log_path', {
    path: logPath
  });

  if (!validation.valid) {
    throw new Error(validation.error_message ?? 'Invalid path');
  }

  return logPath;
}

async function appendNote(path: string, text: string): Promise<void> {
  const now = new Date();
  const pad = (n: number) => String(n).padStart(2, '0');
  const timestamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
  await invoke('append_to_file', {
    path,
    content: `- [${timestamp}] ${text}`
  });
}

Build docs developers (and LLMs) love

Get started for freeTalk to us