Getting Started

Use this section when you are new to Arashi and need a quick setup and first workflow.

Install

Choose either install method below.

Prerequisites

• git available in your shell
• bash and curl for the curl installer path
• node and npm for the npm path

Method 1: curl installer

curl -fsSL https://arashi.haphazard.dev/install | bash

Pin a specific version when needed:

curl -fsSL https://arashi.haphazard.dev/install | ARASHI_VERSION=1.4.0 bash

Verify install:

arashi --version

The installer defaults to ~/.arashi/bin, updates your shell profile so arashi is available on PATH in new shells, and in interactive installs can offer shell integration for arashi switch --cd. It also runs a quick arashi --version smoke test before declaring success.

For unattended installs, set ARASHI_SHELL_INTEGRATION=yes to enable that automatically or ARASHI_SHELL_INTEGRATION=no to skip it.

If this path fails, use npm (npm install -g arashi) or the manual release flow in repos/arashi/docs/INSTALLATION.md.

Method 2: npm global install

npm install -g arashi

Arashi downloads the matching platform binary on first use. To preinstall it explicitly:

arashi install

Verify install:

arashi --version

If npm is unavailable or binary installation fails in your environment, use the curl installer command above or the manual release flow in repos/arashi/docs/INSTALLATION.md.

Troubleshooting and fallback

• command not found: install missing prerequisite (curl, bash, npm, or node) and rerun.
• Permission errors writing to global paths: rerun curl with ARASHI_INSTALL_DIR="$HOME/.local/bin" or use a user-level npm prefix.
• Network/download failures: retry once; for npm installs you can rerun arashi install, then switch to the other install method if needed.
• Checksum mismatch on curl path: stop and use npm/manual fallback, then report the failure.
• If arashi --version exits immediately or returns code 137, rerun the curl installer with ARASHI_VERSION=<version> to pin a known-good release, or use npm/manual install while reporting the bad release artifact.

First Workflow

Start with the path that matches how you are adopting Arashi.

1. Create a new meta-repo

Use this flow when you are starting fresh and want Arashi to initialize the workspace root.

mkdir my-meta-repo
cd my-meta-repo
arashi init

When prompted for the repository target, enter . to initialize the current directory.

2. Add Arashi to an existing meta-repo

Use this flow when you already have a repository that should become your Arashi workspace.

cd path/to/existing-meta-repo
arashi init

Run arashi init from the repository root you want Arashi to manage.

Once arashi init completes, continue with the core workflow:

arashi add [email protected]:your-org/frontend.git
arashi create feature-docs-bootstrap
arashi switch feature-docs-bootstrap
arashi status

By default, new managed worktrees are created under .arashi/worktrees. Set command defaults in .arashi/config.json (defaults.create, defaults.switch) to define preferred switch and launch behavior, and use arashi shell install if you want arashi switch to support parent-shell cd behavior.

If you install Arashi with the official curl installer, it can offer shell integration during install so arashi switch --cd works without an extra setup step.

When the workspace is initialized, choose the workflow guide that matches what you need next:

• Hooks for lifecycle automation after create and remove.
• Config for command defaults and shell-aware switching behavior.
• VS Code for editor-first worktree management.
• tmux and sesh for terminal-native switching and session flows.
• Agents for implementation boundaries and meta-repo guidance.

Next Steps

• Continue to Commands for command-by-command behavior.
• Continue to Workflows if you want setup guidance by workflow instead of by command.
• Continue to Contributing if you want to make a project change.