Getting Started with the CLI

Quick start guide for the Zipwire CLI

Get up and running with the Zipwire CLI in just a few minutes.

Prefer MCP clients? If you'd rather use an MCP-compatible tool instead of the command line, check out Zipwire's MCP Server. Connect Claude Desktop, custom agents, or any MCP client to manage timesheets, activities, workflows, and more—no CLI commands needed.

Installation

The Zipwire CLI is published on npm as @zipwire/zw. You can install it globally with npm, run it once with npx, or build from source.

Via NPM (Recommended)

Install the CLI globally so the zw command is available everywhere:

npm install -g @zipwire/zw

You need Node.js and npm installed first. The -g flag installs the binary globally and adds it to your PATH.

After installation, verify it works:

zw --version

To upgrade to the latest version later:

npm update -g @zipwire/zw

Via npx (No Installation)

If you prefer not to install globally, you can run the CLI with npx. Each run downloads the package if needed:

npx @zipwire/zw --help
npx @zipwire/zw activity list
npx @zipwire/zw journal track "Quick entry" -d 1h --activity "Company > Project"

Useful for trying the CLI or running it in CI without a global install.

From Source

If you have Go installed and want to build from source:

git clone https://github.com/zipwireapp/zwcli.git
cd zwcli
go build -o zw ./cmd/zw
sudo mv zw /usr/local/bin/

Or install directly with go install:

go install github.com/lukepuplett/zwcli/cmd/zw@latest

Ensure your Go bin directory (e.g. ~/go/bin) is on your PATH so the zw command is found.

See the CLI repository for more details.

Step 1: Authenticate

Before you can use the CLI, you need to authenticate with Zipwire. Choose the option that best fits your situation:

Option A: Sign Up for a New Account (Recommended for New Users)

If you don't have a Zipwire account yet, you can sign up directly from the CLI via WhatsApp:

zw auth signup --name "Your Full Name" --whatsapp "[phone]"

Replace the phone number with your WhatsApp number in E.164 format (e.g., +1 for US, +44 for UK).

What happens automatically:

1. Your API token is stored and ready to use immediately

2. A WhatsApp message from Zipwire's bot arrives with onboarding instructions

3. Follow the bot's prompts in WhatsApp to complete your account activation

Once you receive the bot's welcome confirmation in WhatsApp, return to the CLI and start using it—nothing else to do. Your token is already set up and working.

💡 Tip: Check your WhatsApp spam folder if you don't see the bot's message immediately.

Option B: Browser Login (For Existing Users)

If you already have a Zipwire account, log in via your browser:

zw auth login

This will open your browser automatically, where you can sign in with your passkey or wallet. When complete, your authentication token is saved to ~/.config/zw/config.yaml.

Option C: Manual Token

If you have an API token, you can set it manually:

zw auth set-token your-api-token

Check Authentication Status

zw auth status

You should see something like:

↓ Authentication status
  Authenticated
  Token: zw_...

Step 2: Your First Command

Let's verify everything is working and list your activities:

zw activity list

This shows all the activities you've created in Zipwire. Activities follow the structure: Company > Project > Activity

If you don't have any activities yet, create one:

zw activity create "My Company > First Project > Development"

Step 3: Track Your First Time Entry

Log some time to your journal:

zw journal track "Initial setup and exploration" -d 30m --activity "My Company > First Project > Development"

This creates a journal entry with:

• Description: "Initial setup and exploration"

• Duration: 30 minutes

• Activity: "My Company > First Project > Development"

View your recent entries:

zw journal list --today

Accessing Zipwire on the Web

Once authenticated, you can generate a magic link to access Zipwire's website without needing to log in again:

zw auth login-link

This creates a temporary magic link that you can use in your browser for direct website access.

What's Next?

You now have the basics working! Here's what you can explore:

• Authentication & Security – Learn about tokens, config files, and security best practices

• Configuration – Customize your CLI settings

• Common Workflows – See practical examples (create timesheet, submit for approval, track time, etc.)

Need Help?

The CLI has built-in help for every command:

zw --help                    # General help
zw journal --help           # Help for journal commands
zw journal track --help     # Help for specific command

Or explore the CLI repository for source code and additional documentation.

---

Pro Tip: Use zw --help frequently. The CLI is self-documenting and often the most up-to-date reference.