Back to Project Pak-LLM Coder
Developer Documentation · v1.4.0

pakllm-cli

The decoupled terminal client for Pak-LLM Coder. It ships an Elm-style reactive TUI, in-memory snapshot rollback, bilingual status logs and a headless mode built for CI/CD. It runs on Windows, macOS and Linux with no native dependencies, and can delegate to the Python core engine when one is installed.

Zero native depsEnglish / اردوJSON CI reports

Install

npm / npxnpx @pak-llm/coder
Global npmnpm install -g @pak-llm/coder
pipx (Python core)pipx install pak-llm
Linux / macOScurl -fsSL https://coder.pak-llm.com/install.sh | bash
Windows PowerShellirm https://coder.pak-llm.com/install.ps1 | iex

Set PAK_CODER_RUNTIME=node to force the bundled Node runtime instead of delegating to a Python core engine.

Interactive terminal harness

Launch with pak-coder tui or the /tui slash command. The harness follows a model / update / view loop inspired by bubbletea and ratatui, rendered with zero native bindings so it behaves identically in terminals and CI logs.

KeyAction
dToggle the side-by-side before/after diff for the selected file.
uRestore every file captured in the current snapshot checkpoint.
URestore only the selected file.
rRefresh the snapshot delta from disk.
aToggle auto-approve for shell and file mutations.
lSwitch status language between English and Urdu.
?Show or hide the key map.
q / Ctrl+CLeave the harness without touching the workspace.

Snapshot rollbacks

Before any write or edit, the CLI captures the previous bytes of the target file in an in-memory delta cache. Created files are tracked as absent-before. Nothing touches disk until an undo runs, and files the session never touched are never modified.

pak-coder undo [path]

Restore one file, or every captured mutation, from the in-memory delta cache.

pak-coder snapshot [--json]

Inspect status, diff and checkpoint id for every captured file.

/undo [path]

Interactive equivalent of the undo command.

/snapshot

List the current checkpoint delta inside the session.

Esc Esc

Double Escape reverts the whole checkpoint without leaving the prompt.

Headless CI/CD

-p runs a single prompt without opening a REPL. With --json-report every conversational log is diverted to stderr, so stdout contains exactly one JSON document. The process exits non-zero on failure, which makes it safe to gate a pipeline step on the result.

FlagBehaviour
-p, --prompt <text>Single prompt, no interactive prompts. Exits non-zero when execution fails.
--autoAuto-approve shell and file mutations for unattended CI runs.
--json-reportEmit one machine-readable JSON report on stdout; all logs move to stderr.
--report-file <path>Persist the same JSON report to a file for CI artifacts.
--lang en|urBilingual status logs. Defaults to PAKLLM_LANG or English.
-f, --file <path>Attach file context to the headless prompt.

Report shape

{
  "schemaVersion": "1.0.0",
  "mode": "headless",
  "status": "success",
  "prompt": "add tests for the auth module",
  "language": "en",
  "durationMs": 1842,
  "tokensUsed": 5120,
  "toolsExecuted": 7,
  "filesCreated": ["src/auth.test.ts"],
  "packagesInstalled": [],
  "snapshot": {
    "checkpointId": "snap-m6x1a2",
    "changedFiles": ["src/auth.test.ts"]
  },
  "walkthrough": { "title": "Workspace verification complete" },
  "error": null
}

GitHub Actions

# .github/workflows/pakllm.yml
name: Pak-LLM Coder
on: [pull_request]

jobs:
  migrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Run headless migration
        env:
          PAKLLM_API_KEY: ${{ secrets.PAKLLM_API_KEY }}
        run: |
          npx @pak-llm/coder -p "migrate deprecated APIs and add tests" \
            --auto --json-report --report-file pakllm-report.json
      - uses: actions/upload-artifact@v4
        with:
          name: pakllm-report
          path: pakllm-report.json

Bilingual logs

Every CLI status string has an English and Urdu form. Choose with --lang ur, PAKLLM_LANG=ur, or press l inside the TUI. Headless reports record the selected language in the language field.

Compliance controls

  • NIST SP 800-53 AC-3 / AC-6: snapshot recovery, explicit approval gates and auto-approve limited to explicit --auto.
  • NIST AU-6 / SI-2: every checkpoint and file mutation is traceable; completion is blocked while verification fails.
  • OWASP LLM01 / LLM08: prompt sanitization and least-privilege tool use before any command runs.
  • CWE-22 / CWE-78 / CWE-79: path normalization, argv-only command execution and no unsafe HTML rendering in diffs.

Continue building

pakllm-cli — TUI, Snapshots & Headless CI | Pak-LLM Coder | Pak-LLM Coder