tpix

README

TPIX CLI

A command-line client for managing Typst packages on the TPIX server. For more information about TPIX and TPIX CLI, please visit TPIX.

Installation

Use the install script to download and install the latest stable version if you are using Linux or MacOS:

curl -fsSL https://tpix.typstify.com/install.sh | bash

You can also download pre-built binaries from the GitHub Releases page.

For developers, use the following command to install tpix-cli:

go install github.com//tpix-cli@latest

Or build from source:

git clone https://github.com/typstify/tpix-cli.git
cd tpix-cli
make install

The binary will be built as tpix and installed in /usr/local/bin/ in Linux and MacOS.

Quick Start

# Login to TPIX server
tpix login -k api-key-xxxx

# Search for packages
tpix search "chart"

# Download a package
tpix get @namespace/package-name:1.0.0

# View package info
tpix info @namespace/package-name

Commands

Authentication

tpix login

Login using api key issued by the TPIX server.

# Show the authenticated user
tpix whoami

# Remove the stored API key
tpix logout

Configuration

# Print cache directory path
tpix cache-path

# Set custom cache directory
tpix cache-path --set /custom/path

# Reset to default cache directory
tpix cache-path --set ""

The cache directory can also be set via the TYPST_PACKAGE_CACHE_PATH environment variable, which takes precedence over the saved config value.

Search & Discovery

# Search packages
tpix search "chart"

# Search in specific namespace
tpix search "chart" -n mynamespace

# Limit results
tpix search "chart" -l 10

Download Packages

# Download latest version (with transitive dependencies)
tpix get @namespace/package-name

# Download specific version
tpix get @namespace/package-name:1.0.0

# Download without fetching dependencies
tpix get @namespace/package-name:1.0.0 --no-deps

Pull Project Dependencies

# Scan current directory for .typ imports and fetch all dependencies
tpix pull

# Preview what would be fetched without downloading
tpix pull --dry-run

tpix pull recursively scans all .typ files in the current directory for #import "@namespace/name:version" statements, then downloads each package along with its transitive dependencies. Already-cached packages are skipped.

Package Info

# View package details
tpix info @namespace/package-name

# Show the full transitive dependency tree (no downloads)
tpix deps @namespace/package-name

Local Cache

# List cached packages
tpix list

# Remove cached package
tpix remove @namespace/package-name:1.0.0

Create & Bundle Package

Create a Package or Template skeleton.

# create a template
tpix new -d ~/work -t -n my-namespace my-template

# create a package
tpix new -d ~/work  -n my-namespace my-package

Create a package bundle from a package directory.

# Create package from directory
tpix bundle ./my-package

# Specify output file
tpix bundle ./my-package -o my-package.tar.gz

# Exclude files
tpix bundle ./my-package -e ".git" -e "node_modules/" -e "*.test"

The directory must contain a valid typst.toml manifest with required fields:

[package]
name = "mypackage"
version = "1.0.0"
entrypoint = "lib.typ"
authors = ["Your Name"]
license = "MIT"
description = "A sample package"

You can also specify excluded files in the manifest:

[package]
# ... other fields
exclude = [".git", "*.test", "node_modules/"]

For more information on how to create a package, please refer to docs in https://github.com/typst/packages/tree/main/docs & https://tpix.typstify.com/docs/package.

Upload Package

# Upload to namespace
tpix push my-package.tar.gz mynamespace

Zotero Export

# List accessible Zotero libraries
tpix zotero list

# Create and download an export (interactive mode)
tpix zotero export

# Export to a specific file
tpix zotero export -o references.bib

# Export with specific format
tpix zotero export --format bibtex -o references.bib

# Export from specific library
tpix zotero export --library 12345 -o references.bib

tpix zotero export creates a temporary export, downloads the citations, and automatically cleans up. Use --format to specify output format (default: biblatex).

Version & Updates

# Check current version and updates
tpix version

# Update to latest version
tpix update

Output Format

Package specifications use the format @namespace/name:version:

• @user/chart - latest version from user's namespace
• @user/chart:1.0.0 - specific version

Structured output

Pass the global --json flag to get a single structured result document on stdout:

tpix search cetz --json
tpix get @preview/cetz --json

Progress output goes to stderr, so stdout is always a single JSON document. See docs/json-output.md for the full schema.

Documentation

Index

• type DependencyGraph
• type DependencyNode
• type DirectDependency
• type PullResult
• type ReportFunc
• type ResolvedPackage
• type TpixSdk
  • func NewTpixSdk(httpClient *api.HttpClient, store storage.PackageStore) *TpixSdk
  • func (t *TpixSdk) BundlePackage(srcDir string, outputFile string, excludedFiles []string) (string, error)
  • func (t *TpixSdk) CreateZoteroExport(name string, namespaceID string, libraryType string, libraryID int64, ...) (string, error)
  • func (t *TpixSdk) DeleteZoteroExport(exportID string) error
  • func (t *TpixSdk) DownloadPackage(pkgSpec string, noDeps bool) ([]ResolvedPackage, error)
  • func (t *TpixSdk) DownloadProjectDependencies(projectDir string, dryRun bool) (*PullResult, error)
  • func (t *TpixSdk) FetchZoteroExport(exportID string, writer io.Writer) error
  • func (t *TpixSdk) GetNamespacePackages(namespace string) ([]api.PackageResponse, error)
  • func (t *TpixSdk) GetPackageIndex() (string, error)
  • func (t *TpixSdk) GetUserProfile() (*api.UserProfile, error)
  • func (t *TpixSdk) ListZoteroLibraries() ([]api.ZoteroLibrary, error)
  • func (t *TpixSdk) PushPackage(packagePath string, namespace string) (*api.UploadResponse, error)
  • func (t *TpixSdk) QueryPackage(pkgSpec string) (*api.PackageResponse, error)
  • func (t *TpixSdk) ResolveDependencies(pkgSpec string) (*DependencyGraph, error)
  • func (t *TpixSdk) SearchPackages(namespace string, query string, kind string, category string, sort string, ...) (*api.SearchResponse, error)
  • func (t *TpixSdk) WithReporter(reporter ReportFunc)
• type ZoteroLibrary

Types

type DependencyGraph

type DependencyGraph struct {
	Root *DependencyNode
	// Packages is the flattened, de-duplicated set of all packages in the graph.
	Packages []ResolvedPackage
}

DependencyGraph is the resolved dependency graph of a package.

type DependencyNode

type DependencyNode struct {
	Package  deps.Dependency
	Cached   bool
	Children []*DependencyNode
}

DependencyNode is a package together with its resolved dependencies.

type DirectDependency

type DirectDependency struct {
	Package deps.Dependency
	Cached  bool
}

DirectDependency is a direct import discovered while scanning a project.

type PullResult

type PullResult struct {
	ProjectDir string
	DryRun     bool
	Direct     []DirectDependency
	Packages   []ResolvedPackage
}

PullResult is the outcome of DownloadProjectDependencies.

type ReportFunc

type ReportFunc func(message string)

type ResolvedPackage

type ResolvedPackage struct {
	Package deps.Dependency
	Cached  bool
}

ResolvedPackage is a package that was processed during a fetch operation, together with whether it was already present in the local cache.

type TpixSdk

type TpixSdk struct {
	// contains filtered or unexported fields
}

func NewTpixSdk

func NewTpixSdk(httpClient *api.HttpClient, store storage.PackageStore) *TpixSdk

func (*TpixSdk) BundlePackage

func (t *TpixSdk) BundlePackage(srcDir string, outputFile string, excludedFiles []string) (string, error)

func (*TpixSdk) CreateZoteroExport

func (t *TpixSdk) CreateZoteroExport(name string, namespaceID string, libraryType string, libraryID int64, collectionKey string, format string) (string, error)

CreateZoteroExport creates an export target on the TPIX server.

func (*TpixSdk) DeleteZoteroExport

func (t *TpixSdk) DeleteZoteroExport(exportID string) error

DeleteZoteroExport deletes an existing Zotero export.

func (*TpixSdk) DownloadPackage

func (t *TpixSdk) DownloadPackage(pkgSpec string, noDeps bool) ([]ResolvedPackage, error)

DownloadPackage download Typst packages from TPIX server and returns the resolved package list, each tagged with whether it was already cached.

pkgSpec should follow the pattern: @namespace/name:version. Refer to deps.ParseDependency to know details. If noDeps is true, it will skip fetching transitive dependencies.

The first item of the returned slice will always be the pkgSpec.

func (*TpixSdk) DownloadProjectDependencies

func (t *TpixSdk) DownloadProjectDependencies(projectDir string, dryRun bool) (*PullResult, error)

func (*TpixSdk) FetchZoteroExport

func (t *TpixSdk) FetchZoteroExport(exportID string, writer io.Writer) error

FetchZoteroExport fetches the content of a Zotero export.

func (*TpixSdk) GetNamespacePackages

func (t *TpixSdk) GetNamespacePackages(namespace string) ([]api.PackageResponse, error)

GetNamespacePackages fetches all the packages in the specified namespace.

func (*TpixSdk) GetPackageIndex

func (t *TpixSdk) GetPackageIndex() (string, error)

GetPackageIndex retrieves a markdown file containing all user accessible package/template metadata. This API is dedicated for LLM use.

func (*TpixSdk) GetUserProfile

func (t *TpixSdk) GetUserProfile() (*api.UserProfile, error)

GetUserProfile queries the user profile from TPIX server.

func (*TpixSdk) ListZoteroLibraries

func (t *TpixSdk) ListZoteroLibraries() ([]api.ZoteroLibrary, error)

ListZoteroLibraries returns the list of Zotero libraries accessible to the user.

func (*TpixSdk) PushPackage

func (t *TpixSdk) PushPackage(packagePath string, namespace string) (*api.UploadResponse, error)

func (*TpixSdk) QueryPackage

func (t *TpixSdk) QueryPackage(pkgSpec string) (*api.PackageResponse, error)

func (*TpixSdk) ResolveDependencies

func (t *TpixSdk) ResolveDependencies(pkgSpec string) (*DependencyGraph, error)

ResolveDependencies resolves the full dependency graph of pkgSpec without downloading any package. Cache status is read from the local store.

func (*TpixSdk) SearchPackages

func (t *TpixSdk) SearchPackages(namespace string, query string, kind string, category string, sort string, limit int) (*api.SearchResponse, error)

SearchPackages searches Typst packages from TPIX server.

func (*TpixSdk) WithReporter

func (t *TpixSdk) WithReporter(reporter ReportFunc)

type ZoteroLibrary

type ZoteroLibrary = api.ZoteroLibrary

ZoteroLibrary represents a Zotero library.