Skip to content
MANIFOLD by JFA

Overview

Install and use the Manifold CLI for backups, migrations, registry maintenance, and provider operations.

View as Markdown

manifold generates Paperback backups, migrates provider lists, and maintains your canonical registry. This site documents the CLI only.

Installation

Download a manifold-cli-<os>-<arch>.zip archive and its .sha256 checksum from GitHub Releases, choosing a cli-v* release for your platform. Verify the checksum, extract the archive, and put manifold (or manifold.exe on Windows) on your PATH. Linux binaries support x64 and arm64; macOS supports arm64; Windows supports x64.

From an installed binary:

manifold --help
manifold --version

Self-update with upgrade.

To run from source, install Bun, clone the repository, and run from its root:

git clone https://github.com/jfalava/manifold.git
cd manifold
bun install
bun run manifold --help

In the examples below, replace manifold with bun run manifold when running from source. The root script runs inside cli/, so relative input/output paths resolve there, not at the repository root. Use absolute paths when needed.

Command reference

Use manifold <command> --help for the installed version’s flags.

Global flags

--help, -h

Print help for the selected command without running it.

manifold pas5 create --help

--version, -v

Print the installed CLI version.

manifold --version

--wizard

Start the interactive wizard for a command. Default: off.

manifold pas5 create --wizard

--completions <bash|zsh|fish|sh>

Print a completion script for the selected shell. Load the output using your shell’s completion setup.

manifold --completions zsh

--log-level <level>

Set the minimum log level for this invocation. Accepted values: all, trace, debug, info, warn, warning, error, fatal, and none.

manifold ops pending --log-level debug

Preview a registry backup

manifold login manifold
manifold pas5 create --source registry --limit 10 --tabs none --out ./Paperback-Registry-10.pas5

Review the dry-run report, then repeat with --apply to write the file. --tabs none keeps eligible titles without list state. The registry limit selects the first ten active rows before eligibility checks, so skipped entries can produce fewer than ten titles. See pas5 for the full reference.

Configuration

Remote-touching commands resolve credentials in this order: flag → MANIFOLD_* env → OS keychain login where applicable (from cli/.env, the process environment, or login manifold / login anilist / login mal).

Manifold authentication

Sign in with GitHub through login manifold. No separate OAuth client registration or API token is required for the default API:

manifold login manifold

The session is stored in the OS keychain and refreshes on later API use. On a headless host, use --paste-only and paste the callback URL after authorizing in another browser.

A stale MANIFOLD_TOKEN overrides a successful keychain login. Remove it from cli/.env and the process environment to use the saved session. For a one-off command, an empty process value prevents the dotenv file from supplying it:

MANIFOLD_TOKEN= manifold pas5 create --source registry --limit 10 --tabs none

--api-token <token>

Personal API token override for pas5 create, ops, reconcile, registry, and MAL backup checks. Falls back to MANIFOLD_TOKEN, then the login manifold keychain session. Explicit tokens do not refresh. Prefer keychain login; flags may expose secrets in shell history or process arguments.

Example:

manifold ops pending --api-token "$MANIFOLD_TOKEN"

--api-origin <url>

Personal API origin for pas5 create, ops, reconcile, registry, and MAL backup checks. Falls back to MANIFOLD_API_ORIGIN.

  • Default: https://manifold.jfa.dev/api

Example:

manifold reconcile diff --api-origin https://manifold.example/api

AniList authentication

Prefer local OAuth over pasting tokens. Full setup: login anilist.

manifold login anilist

Register a separate authorization-code client with redirect URI http://127.0.0.1:8767/callback, then set MANIFOLD_ANILIST_CLIENT_ID and MANIFOLD_ANILIST_CLIENT_SECRET in cli/.env. The access token is stored in the OS keychain (manifold / anilist-session). On a headless host use --paste-only and paste the callback URL after authorizing in another browser. AniList does not issue refresh tokens — re-run login when the session expires.

--anilist-token <token>

Optional AniList access token override for AniList operations, pas5 create --source anilist, migrations, reconciliation, registry import, and draining AniList writes. Resolve order: flag → MANIFOLD_ANILIST_TOKEN → keychain login.

Example:

manifold login anilist
manifold registry import

MyAnimeList authentication

Prefer local OAuth over pasting tokens. Full setup: login mal. Consumers: mal wipe manga, migrate anilist-to-mal.

manifold login mal

Register a separate MAL OAuth client with redirect URI http://127.0.0.1:8766/callback, then set MANIFOLD_MAL_CLIENT_ID in cli/.env (and MANIFOLD_MAL_CLIENT_SECRET if required). Access and refresh tokens live in the OS keychain (manifold / mal-session); rotated refresh tokens are saved automatically. On a headless host use --paste-only and paste the callback URL after authorizing elsewhere. Do not reuse the deployed API’s client or refresh token.

--mal-token <token>

Optional MAL access token override for mal wipe manga and migrate anilist-to-mal. Resolve order: flag → MANIFOLD_MAL_TOKEN → keychain login. A supplied token does not refresh.

Example:

manifold login mal
manifold mal wipe manga

registry mal audits active registry entries and backfills verified MAL links from AniList without importing MAL list state or requiring MAL authentication. See registry mal.

migrate anilist-to-mangadex, mangadex stale-status, and mangadex unfollow-dropped require all four MangaDex credentials.

--mangadex-client-id <id>

OAuth client ID for the MangaDex password grant. Falls back to MANIFOLD_MANGADEX_CLIENT_ID.

Example:

manifold mangadex stale-status --mangadex-client-id "$MANIFOLD_MANGADEX_CLIENT_ID"

--mangadex-client-secret <secret>

OAuth client secret for the MangaDex password grant. Falls back to MANIFOLD_MANGADEX_CLIENT_SECRET.

Example:

manifold mangadex stale-status --mangadex-client-secret "$MANIFOLD_MANGADEX_CLIENT_SECRET"

--mangadex-username <username>

MangaDex account username for the password grant. Falls back to MANIFOLD_MANGADEX_USERNAME.

Example:

manifold mangadex stale-status --mangadex-username "$MANIFOLD_MANGADEX_USERNAME"

--mangadex-password <password>

MangaDex account password for the password grant. Falls back to MANIFOLD_MANGADEX_PASSWORD.

Example:

manifold mangadex stale-status --mangadex-password "$MANIFOLD_MANGADEX_PASSWORD"

MangaDex credentials together

Pass all four flags when credentials are not available through the environment:

Example:

manifold mangadex stale-status \
  --mangadex-client-id "$MANIFOLD_MANGADEX_CLIENT_ID" \
  --mangadex-client-secret "$MANIFOLD_MANGADEX_CLIENT_SECRET" \
  --mangadex-username "$MANIFOLD_MANGADEX_USERNAME" \
  --mangadex-password "$MANIFOLD_MANGADEX_PASSWORD"

AniList writes always run on your machine — AniList blocks Cloudflare Worker egress IPs, which is also why anilist:* ops drain on the device rather than the Worker.

Dry-run defaults

Library, registry, and queued-operation writes are dry-run until --apply. anilist wipe manga --apply also requires interactive confirmation unless --yes is present. mal wipe manga --apply requires --backup-paused instead of a prompt, and refuses to delete while the API’s MAL connection is still active.

Exit codes

Human-readable tables and summaries go to stdout. Non-zero exit means failure — usually an upstream HTTP error (AniList rate limits: expect ~2.5 s spacing and 429 backoff) or a missing token.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close