# How to Manage Local Distillation Jobs with distilly pending

> Manage local distillation jobs with distilly pending. List, inspect, cancel, and clean up unfinished jobs stored as JSON manifests. Streamline your workflow with this powerful tool.

- Repository: [Tianyi Zhou/distilly](https://github.com/titanwings/distilly)
- Tags: how-to-guide
- Published: 2026-09-10

---

**Use the `distilly pending` subcommand group to list, inspect, cancel, and clean up unfinished distillation jobs stored as JSON manifests in the `.distilly/pending/` directory.**

The `titanwings/distilly` repository provides a local job queue for managing distillation workflows before they are finalized. The `distilly pending` CLI commands—defined in `bin/distilly.mjs`—allow you to interact with this queue, giving you precise control over which jobs are processed, cancelled, or removed based on age.

## Where Pending Jobs Are Stored

When you initiate a distillation, the CLI creates a JSON manifest inside the hidden directory **`.distilly/pending/`** at your project root. According to the logic in [`tools/skill_writer.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_writer.py), each manifest file is named by a unique **job‑id** (generated via `uuid4`) and tracks:

- **family** – the distillation type (`colleague`, `relationship`, or `celebrity`)
- **sources** – file paths, URLs, or chat exports used as input
- **params** – runtime settings such as model, temperature, and output format
- **timestamps** – `created` and `last‑updated` fields for lifecycle management

These manifests remain in the queue until you explicitly apply or cancel them.

## Listing and Inspecting Jobs

### Listing All Pending Jobs

The `distilly pending list` command iterates over `.distilly/pending/` and prints a summary table showing the **ID**, **Family**, **Created** date, and current status.

```bash

# Display every job waiting to be processed

$ distilly pending list
┌───────────────────────┬─────────────┬─────────────────────┐
│ ID                    │ Family      │ Created             │
├───────────────────────┼─────────────┼─────────────────────┤
│ 9f7d2c4e-a1b3-4d5e-…  │ colleague   │ 2026-08-22 14:03:12 │
│ a12c9b1f-e8f7-44d2-…  │ celebrity   │ 2026-08-23 09:47:05 │
└───────────────────────┴─────────────┴─────────────────────┘

```

### Viewing Job Details

To audit a specific job before committing resources, run `distilly pending show <job-id>`. This outputs the full JSON manifest so you can verify source locations and parameters.

```bash

# Inspect a single pending job

$ distilly pending show 9f7d2c4e-a1b3-4d5e-...
{
  "id": "9f7d2c4e-a1b3-4d5e-...",
  "family": "colleague",
  "sources": ["./data/lark_export.json"],
  "params": {
    "model": "gpt-4o",
    "temperature": 0.2
  },
  "created": "2026-08-22T14:03:12Z",
  "last_updated": "2026-08-22T14:03:12Z"
}

```

## Cancelling and Pruning Jobs

### Cancel a Specific Job

If you need to abort a distillation, `distilly pending cancel <job-id>` removes the manifest from the queue and deletes any temporary working directories created by [`tools/skill_writer.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_writer.py).

```bash

# Remove a job from the queue

$ distilly pending cancel a12c9b1f-e8f7-44d2-...
✔ Removed pending job a12c9b1f-e8f7-44d2-...

```

### Clean Up Old Jobs

For automated maintenance, the `prune` subcommand deletes jobs older than a specified threshold. This is useful in CI pipelines to prevent the queue from growing indefinitely.

```bash

# Delete jobs older than 7 days

$ distilly pending prune --older-than 7
🗑 Deleted 3 stale pending jobs

```

## Finalizing Pending Jobs

A job leaves the queue when it is **applied**. Whether triggered manually via `distilly apply <job-id>` or automatically after a successful run, the CLI performs three steps defined in the core processing logic:

1. Loads the manifest from `.distilly/pending/`.
2. Executes the appropriate family pipeline (e.g., the six‑dimension celebrity research chain) to generate the **Person Profile**.
3. Writes the result to the `skill/` directory and deletes the JSON manifest from the queue.

Once this completes, the job no longer appears in `distilly pending list` because the source files have been removed.

```bash

# Finalize a pending job and write output to skill/

$ distilly apply 9f7d2c4e-a1b3-4d5e-...
✔ Applied colleague distillation → skill/colleague_9f7d2c4e.md

```

## Summary

- **Storage location** – Pending jobs live in `.distilly/pending/` as JSON manifests tracked by [`tools/skill_writer.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_writer.py).
- **Inspection** – Use `distilly pending list` for overviews and `distilly pending show` for detailed manifests.
- **Lifecycle management** – Cancel individual jobs with `cancel` or bulk‑remove stale entries with `prune --older-than`.
- **Completion workflow** – Running `distilly apply` moves the output to `skill/` and automatically cleans the queue.

## Frequently Asked Questions

### Where does distilly store pending job manifests?

The CLI writes every unfinished job to the hidden directory `.distilly/pending/` at the project root. Each file is a JSON document named by its UUID and contains the family type, source references, runtime parameters, and timestamps required to resume or cancel the task.

### How do I stop a distillation job before it runs?

Execute `distilly pending cancel <job-id>`. This command—handled by the CLI parser in `bin/distilly.mjs`—deletes the manifest and any scratch data created by the skill writer, ensuring the job never enters the processing pipeline.

### What is the difference between cancel and prune?

**Cancel** targets a single job by its UUID and removes it immediately, regardless of age. **Prune** scans the entire `.distilly/pending/` folder and deletes every job whose `created` timestamp exceeds the specified day limit, making it ideal for scheduled cleanup in automated environments.

### How does a job move from pending to completed?

When you run `distilly apply <job-id>` or the system auto‑processes the queue, the CLI reads the manifest, runs the relevant family pipeline (colleague, relationship, or celebrity), writes the resulting Person Profile into the `skill/` directory, and removes the JSON file from `.distilly/pending/`. After this step, the job is no longer listed in the pending queue.