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

Via NPM (Recommended)

npm install -g @zipwire/zw

After installation, verify it works:

zw --version

Via npx (No Installation)

Don't want to install? Use npx:

npx @zipwire/zw --help
npx @zipwire/zw activity list

From Source

For developers who 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/

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.