Commands

Reference for all Pinarkive CLI commands (from @pinarkive/pinarkive-cli (opens in a new tab), current version 1.0.2). Commands that call the API require pinarkive login first (or a valid API key in ~/.pinarkive/config.json). The CLI uses the official @pinarkive/pinarkive-sdk-ts (opens in a new tab) for API requests.

API base: https://api.pinarkive.com/api/v3
Gateway: https://gateway.pinarkive.com/ipfs

Commands that do not require authentication

gateway <cid>

Print the gateway URL for a CID. Does not call the API.

pinarkive gateway bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Output: https://gateway.pinarkive.com/ipfs/<cid>

open <cid>

Open the gateway URL in your default browser. Does not call the API.

pinarkive open <cid>

Authentication

login

Save your API key in the local config file. Does not verify the key with the API.

pinarkive login

You'll be prompted: API key: . The key is written to ~/.pinarkive/config.json (or %USERPROFILE%\.pinarkive\config.json on Windows).

Files and pins

upload <file>

Upload a single file. Requires authentication.

pinarkive upload file.png
pinarkive upload ./docs/document.pdf

API: POST /api/v3/files (multipart file).
Output: CID, size (if returned), and gateway URL.

Errors: "Not authenticated. Run: pinarkive login" · "File not found: <path>" · Upload failed message.

pin <cid>

Pin an existing CID to your account. Requires authentication.

pinarkive pin bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

API: POST /api/v3/files/pin/:cid

files

List your uploads. Requires authentication.

pinarkive files

API: GET /api/v3/users/me/uploads
Output: Table with CID, Size, Cluster, Created. If empty: "No files found."

delete <cid>

Remove a pin by CID. Requires authentication.

pinarkive delete bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

API: DELETE /api/v3/files/remove/:cid

clusters

List clusters available to your account. Requires authentication.

pinarkive clusters

API: GET /api/v3/users/me/clusters
Output: Cluster names/IDs and related info. If empty: "No clusters found."

Account and diagnostics

whoami

Show the authenticated user's info. Requires authentication.

pinarkive whoami

API: GET /api/v3/users/me
Output: User (email/username), Plan, Clusters count.

doctor

Run connectivity and auth checks. Does not modify anything.

pinarkive doctor

Checks: API reachable, API key valid, gateway reachable, cluster access.
Exit code: 0 if all pass, 1 if any fail. Useful for troubleshooting.

Sharing and templates

share <file> [options]

Encrypt a file locally (AES-256-GCM), upload it to Pinarkive, and print a share link with the password in the URL fragment.

pinarkive share document.pdf
pinarkive share document.pdf -p mypassword
pinarkive share document.pdf --expires 2025-12-31 --cluster mycluster

Flow: Prompt for password (if not given) → encrypt file locally → upload encrypted blob via POST /api/v3/files → print CID and share link.
Share link format: https://pinarkive.com/#/<cid>:<password> (password is URL-encoded).

init

Create a new project from a template (GitHub: pinarkive/pinarkive-templates). Does not use the Pinarkive API.

pinarkive init

Flow: Fetch templates (e.g. express-api, next-upload, node-script, python-upload, secure-share) → prompt to select template → prompt for project folder name → clone with degit into current directory.
Output: Next steps: cd <folder>, npm install, pinarkive login (if needed).

Watch folder

watch <folder>

Watch a directory and upload new files as they appear. Requires authentication.

pinarkive watch ./my-folder

Behavior: Watches the folder with chokidar (no initial upload of existing files). When a new file is added, the CLI uploads it (POST /api/v3/files) and then pins the CID (POST /api/v3/files/pin/:cid). Prints each new file and its CID.
Stop: Ctrl+C.
Errors: "Folder not found or not a directory" if the path is invalid.

Summary table

API endpoints used: POST /files, POST /files/pin/:cid, GET /users/me/uploads, DELETE /files/remove/:cid, GET /users/me/clusters, GET /users/me.

For the latest options and flags:

pinarkive --help
pinarkive upload --help

Install: npm install -g pinarkive (wrapper, latest) or npm install -g @pinarkive/pinarkive-cli (specific version). See Installation.