ak journal
ak journal
Create and inspect local technical work journals without treating them as durable project authority.
Use ak journal to manage chronological Markdown work records under a
project's plans/journals/ directory. Journal entries can explain completed
work or an incident, but they are historical notes rather than current specs,
ADRs, or other durable authority.
Choose a subcommand
| Goal | Command | Effect |
|---|---|---|
| Write a new entry | ak journal create <title> | Creates one collision-safe Markdown file. |
| Find entries | ak journal list | Reads summaries and applies optional project, date, and text filters. |
| Read one entry | ak journal show <id-or-slug> | Prints the selected Markdown entry. |
| Check one entry | ak journal validate <path-or-id> | Checks its title, date, readability, and .md extension. |
Running ak journal without a subcommand displays help and does not read or
write journal files.
Understand project selection
create, show, and validate accept --project <name>. The value is an
exact registered project name, not a filesystem path. Without the flag,
AgentKit first looks for a registered project containing the current working
directory.
If no registration contains the current directory, create and validate
fall back to that directory. list and show instead continue with its base
name as a registry name; they usually return empty/not found, but can select a
different registered directory with the same name. Register the directory or
pass an explicit --project before relying on name- or ID-based discovery.
Safety and privacy
This command family is local: it does not contact a registry, provider, or
other network service, and it does not start another process. Only create
mutates journal content. It does not prompt, preview, create a backup, or offer
--force; it allocates a new filename instead of overwriting an entry.
Journal bodies, summaries, filenames, and absolute paths can appear on stdout
or in JSON. Treat that output as project content before saving it to logs or
sharing it. Do not pipe credentials or other secrets to create --stdin.
Output and exit behavior
Successful subcommands write their human or versioned JSON result to stdout.
--quiet suppresses success stdout. JSON kinds are journal.create,
journal.list, journal.show, and journal.validate.
Runtime errors in this family are not emitted through the shared JSON error
renderer. With --json, a failed lookup or I/O operation can therefore exit
nonzero without a JSON object on stderr. Flag-parse errors remain plain text.
Treat the process exit code as required evidence.
Exit meanings are subcommand-specific: 1 is a missing entry or I/O failure,
2 is invalid input or project selection, and 3 is a completed validation
whose result is invalid.