Skip to Content
Takumi

Install and upgrade

Install the takumi CLI from npm, as a prebuilt binary with cargo binstall, or build it with cargo install, keep it up to date, and remove it.

Install takumi in one of three ways:

WayNeedsTakes
npmNode.js 18 or laterSeconds
cargo binstallCargo and cargo-binstallSeconds
cargo installRust 1.91 or laterA few minutes

Install from npm

@takumi-rs/cli runs takumi without Rust. Run it once with npx:

npx @takumi-rs/cli image card.html -o card.png --width 1200 --height 630

Render from the command line explains image and its flags.

To keep it in a project, add it as a dev dependency. The project's scripts can then call takumi:

npm i -D @takumi-rs/cli

To call takumi from any directory, install it globally instead:

npm i -g @takumi-rs/cli

The package ships a binary for each of these platforms:

  • macOS on x64 and arm64
  • Windows on x64 and arm64
  • Linux on x64 and arm64, statically linked so that it runs on glibc and musl systems such as Alpine

The binary arrives as an optional dependency. If your package manager skips optional dependencies, such as npm install --omit=optional, takumi exits with an error that names the package it is missing. Install again without skipping them.

Install Rust

cargo binstall and cargo install both run through Cargo. Skip this step if cargo --version prints a version. cargo install needs version 1.91 or later.

Install Rust with rustup, which also puts Cargo on your PATH:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

On Windows, download and run rustup-init.exe from rustup.rs instead.

If you already have an older Rust, update it with rustup update.

Install a prebuilt binary with cargo binstall

cargo-binstall downloads the binary from the takumi release on GitHub and puts it in ~/.cargo/bin:

cargo binstall takumi-cli

If Cargo says no such command: binstall, install cargo-binstall first by following its instructions.

Releases carry binaries for the same platforms as npm. On any other platform, cargo binstall builds takumi from source the way cargo install does, which needs Rust 1.91 or later.

Check that it runs:

takumi --version

Build from source

cargo install --locked takumi-cli

Cargo builds the takumi binary in release mode and puts it in ~/.cargo/bin. The first build takes a few minutes. Check that it runs:

takumi --version

--locked builds with the dependency versions takumi was tested with. To install a particular release, add --version <version>.

Install the latest unreleased version

Changes reach the GitHub repository before they reach a release. To build from the repository's default branch instead of crates.io:

cargo install --locked --git https://github.com/kane50613/takumi takumi-cli

To follow another branch, add --branch <name>. To pin a commit or tag, add --rev <commit> or --tag <tag>.

To build from a clone of the repository, run this in its root:

cargo install --locked --path takumi-cli

Upgrade

Upgrade takumi the way you installed it:

  • From npm, install the newest release again: npm i -D @takumi-rs/cli@latest in a project, or npm i -g @takumi-rs/cli@latest for a global install. npm update stays within the version range in package.json, which does not cross a minor release before 1.0.
  • With cargo binstall, run cargo binstall takumi-cli again to download the newest release.
  • With cargo install, run takumi upgrade.

Upgrade an install from cargo install

takumi upgrade

takumi upgrade reinstalls takumi from the source Cargo recorded when you installed it, into the same directory:

  • An install from crates.io moves to the newest release.
  • An install that followed a branch moves to that branch's latest commit.

It never checks for updates on its own.

To see the cargo install command it would run without running it, add --dry-run:

takumi upgrade --dry-run

takumi upgrade does not run when it cannot move the install forward. It prints the command to run instead, to standard error, and exits with code 1, with or without --dry-run:

  • A Git install pinned with --tag or --rev stays at that pin. The printed command follows the default branch instead.
  • An install from a local clone upgrades after you pull the clone. The printed command rebuilds from it.
  • A binary that cargo install did not install, such as one copied from another machine, upgrades the way you installed it.

On Windows, a running program cannot be replaced. takumi upgrade prints the cargo install command instead and exits with code 1. Run the command in PowerShell once takumi has exited.

The commands takumi prints are quoted for PowerShell on Windows, and for a POSIX shell such as bash or zsh elsewhere.

A printed command leaves out the password in a Git URL, and the user name too unless the URL uses SSH. If the repository needs them, give them to Git another way, such as a credential helper, before you run the command.

Shell completion

takumi completions writes a script that completes takumi's commands, flags, and their values when you press Tab. Save it where your shell reads completions, then open a new shell:

# bash
mkdir -p ~/.local/share/bash-completion/completions
takumi completions bash > ~/.local/share/bash-completion/completions/takumi

# zsh: add `fpath+=~/.zfunc` before `compinit` in ~/.zshrc
mkdir -p ~/.zfunc
takumi completions zsh > ~/.zfunc/_takumi

# fish
mkdir -p ~/.config/fish/completions
takumi completions fish > ~/.config/fish/completions/takumi.fish

# PowerShell: add `. ~/takumi.ps1` to $PROFILE once
takumi completions powershell > ~/takumi.ps1

PowerShell needs the script in a file of its own, since it starts with using statements that must come first in a script.

Run the command again after takumi upgrade, so the script knows the new commands and flags.

Uninstall

Remove an install from npm with your package manager, such as npm uninstall @takumi-rs/cli.

Remove an install from Cargo with cargo uninstall, whether cargo binstall or cargo install put it there:

cargo uninstall takumi-cli

This removes the takumi binary and Cargo's record of it.

Last updated on