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.

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.

Option A: Browser Login (Recommended)

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 B: Manual Token

If you prefer, you can set a token manually:

zw auth login --token your-api-token

Check Authentication Status

zw auth status

You should see something like:

✓ 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

What's Next?

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

• Authentication & Configuration – Learn about tokens, config files, and security

• Configuration – Customize your CLI settings

• Common Workflows – See practical examples (create timesheet, submit for approval, 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.