# Getting Started with the CLI

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

## Installation

The Zipwire CLI is published on [npm](https://www.npmjs.com/package/@zipwire/zw) 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:

```bash
npm install -g @zipwire/zw
```

You need [Node.js](https://nodejs.org/) and npm installed first. The `-g` flag installs the binary globally and adds it to your PATH.

After installation, verify it works:

```bash
zw --version
```

To upgrade to the latest version later:

```bash
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:

```bash
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](https://go.dev/) installed and want to build from source:

```bash
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`:

```bash
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](https://github.com/zipwireapp/zwcli) for more details.

## Step 1: Authenticate

Before you can use the CLI, you need to authenticate with Zipwire.

### Option A: Browser Login (Recommended)

```bash
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:

```bash
zw auth login --token your-api-token
```

### Check Authentication Status

```bash
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:

```bash
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:

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

## Step 3: Track Your First Time Entry

Log some time to your journal:

```bash
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:

```bash
zw journal list --today
```

## What's Next?

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

* [**Authentication & Configuration**](https://docs.zipwire.io/tools-and-integrations/authentication) – Learn about tokens, config files, and security
* [**Configuration**](https://docs.zipwire.io/tools-and-integrations/configuration) – Customize your CLI settings
* [**Common Workflows**](https://docs.zipwire.io/tools-and-integrations/workflows) – See practical examples (create timesheet, submit for approval, etc.)

## Need Help?

The CLI has built-in help for every command:

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

Or explore the [CLI repository](https://github.com/zipwireapp/zwcli) 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.