Code Journal CLI

Project memory, right where you work.

Knowledge and work history · Agent integrations · Offline queue · Git context

The open-source cj client connects developers and AI coding agents to Code Journal. Capture discoveries, maintain plans and tasks, and carry useful context from one session to the next. The hosted service owns journal storage and business rules; this client handles terminal commands, local Git observations, agent hooks, and offline delivery.

codejournal.online

---

Install

Homebrew

On macOS or Linux:

brew install illegalstudio/tap/codejournal-cli
cj --version

mise

Install the published binary with mise:

mise use -g github:illegalstudio/codejournal-cli@0.1.0
cj --version

Use @latest to follow stable releases. mise waits 24 hours before selecting a newly published release with latest; an explicit version installs it immediately. See mise release-age settings.

Direct download

Download an archive for your operating system and processor from Releases, verify it against the release's SHA256SUMS, and put cj on your PATH.

For a user-local installation on macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/illegalstudio/codejournal-cli/main/install.sh | sh

The installer verifies the published checksum before installing into ~/.local/bin. Add that directory to your PATH. Set CJ_VERSION=0.1.0 to choose a release or CJ_INSTALL_DIR to choose the installation directory.

On Windows, download the ZIP archive or use Scoop:

scoop install https://github.com/illegalstudio/codejournal-cli/releases/latest/download/codejournal-cli.json

Connect your account

Create and verify a Code Journal account on the service you use. Pass its URL explicitly:

cj --server https://codejournal.online login
cj whoami
cj setup agents --dry-run
cj setup agents

Login opens browser approval for the device and saves the selected service and workspace. Tokens use the system keyring where available, with a user-only file fallback. cj logout revokes the device token. The public service is being prepared. If you use another Code Journal service, pass its URL explicitly to cj login.

Agent setup supports Codex, Claude Code, Cursor, Grok, Kimi Code, and Pi. It installs the embedded Code Journal skill, preserves unrelated settings, and backs up settings it changes. Review and trust newly installed Codex hooks with /hooks. Grok, Kimi Code, and Pi receive a managed instruction block that loads the skill; setup preserves the rest of your instructions.

To select an agent or remove the managed integration:

cj setup agents --agent kimi
cj setup agents --agent kimi --uninstall

Update

Use the same package manager that installed the CLI:

brew update && brew upgrade illegalstudio/tap/codejournal-cli
# Or, for mise:
mise upgrade github:illegalstudio/codejournal-cli
cj setup agents --refresh
cj --version
cj sync

For a direct installation, cj update downloads the latest stable release, verifies its checksum, replaces the binary, and refreshes your installed agent skills. cj update --check checks for a release without changing anything. Package-managed binaries are protected from direct replacement.

The server can require a minimum CLI version. If your version is no longer supported, cj shows the installed and required releases with update instructions. Agent session hooks pass that notice to your coding agent too. With mise, select the required release explicitly using mise use -g github:illegalstudio/codejournal-cli@VERSION if latest has not picked it up yet. After updating, verify cj --version, refresh agent instructions with cj setup agents --refresh, and run cj sync.

While an update is required, cached reads are not fresh and queued writes have not reached the server. Keep the outbox so synchronization can retry safely after the upgrade. Every backend request identifies the installed release, and the service records it with the data written by the CLI.

Start a project journal

Run these commands in your Git repository:

cj project init
cj brief
cj add --kind discovery --title "Cache invalidation" --body "Record what future sessions should know."
cj search cache
cj log add --title "Completed the cache fix" --status done --body "Describe the change and validation."
cj open

Use cj --help and cj <command> --help for the full interface. The embedded skill explains plans, tasks, docs, refs, maintenance, and the agent workflow.

Offline work

Reads can use cached responses; writes and hook events queue locally when delivery is deferred. Inspect and replay queued work with:

cj status
cj outbox list
cj sync

Use --offline to request queued writes and cached reads explicitly. Avoid storing secrets in journal content.

Licensed under MIT.