# Configuration

The Zipwire CLI stores configuration in a YAML file. This guide covers the available settings and how to customize them for your workflow.

## Config File Location

Your configuration is stored at:

```bash
~/.config/zw/config.yaml
```

To view your current configuration:

```bash
zw config show
```

## Configuration Options

### API Settings

#### `api-base-url`

The API endpoint the CLI connects to.

```yaml
api-base-url: https://api.zipwire.io
```

Usually you don't need to change this, but it's useful if you're running a local Zipwire instance.

#### `api-token`

Your authentication token. Set via `zw auth login`.

```yaml
api-token: zw_your_token_...
```

**Never commit this to version control.** Use environment variables in CI/CD instead.

### Output Settings

#### `output-format`

Controls the output format for all commands.

```yaml
output-format: human
```

Options:

* `human` – Pretty-printed, hierarchical output with colors (default)
* `structured` – Machine-readable key-value format

Override per-command:

```bash
zw activity list --format structured
```

#### `no-color`

Disable colored output.

```yaml
no-color: false
```

Options:

* `false` – Colors enabled (default)
* `true` – Disable all colors

Override per-command:

```bash
zw activity list --no-color
```

The CLI automatically detects if output is being piped and disables colors when appropriate.

## Customizing Configuration

### Via Command Line

Use the `zw config` command to update settings:

```bash
zw config set output-format structured
zw config show
```

### Manual Editing

Edit `~/.config/zw/config.yaml` directly:

```yaml
api-base-url: https://api.zipwire.io
api-token: zw_...
output-format: human
no-color: false
```

## Using Environment Variables

Override config settings with environment variables:

```bash
# Override token
export ZW_API_TOKEN="zw_..."

# Override output format
export ZW_OUTPUT_FORMAT="structured"

# Override base URL
export ZW_API_BASE_URL="https://local.zipwire.io"
```

This is useful for CI/CD pipelines and scripts:

```bash
#!/bin/bash
export ZW_API_TOKEN="$GITHUB_TOKEN"
export ZW_OUTPUT_FORMAT="structured"

zw journal list | jq '.entries[] | select(.duration > 480)'
```

## Per-Command Overrides

Most commands accept flags to override config settings:

```bash
# Override output format for this command
zw activity list --format structured

# Disable colors for this command
zw journal list --no-color

# Specify a config file
zw activity list --config ~/.config/zw/custom-config.yaml
```

Use `--help` to see all available flags for a command:

```bash
zw journal track --help
```

## Multiple Configurations

If you need different configurations for different contexts (work vs. personal, different clients, etc.), create multiple config files:

```bash
# Create alternate config
cp ~/.config/zw/config.yaml ~/.config/zw/work-config.yaml

# Edit as needed
vim ~/.config/zw/work-config.yaml

# Use it
zw activity list --config ~/.config/zw/work-config.yaml
```

## Smart Parsing

The CLI has smart parsing for common values:

### Activity Names

Activities use the hierarchy format:

```
"Company > Project > Activity Name"
```

Must be quoted if they contain spaces or special characters:

```bash
# ❌ Wrong
zw journal track Work on bug > Development

# ✅ Right
zw journal track "Work on bug" --activity "Company > Development"
```

### Dates

Dates are parsed intelligently:

```bash
zw journal list --from today
zw journal list --from yesterday
zw journal list --from Monday
zw journal list --from "2024-01-01"
zw journal list --from "2025-W10"  # ISO week format
```

### Durations

Durations are flexible:

```bash
zw journal track "Work" -d 45m      # 45 minutes
zw journal track "Work" -d 2h       # 2 hours
zw journal track "Work" -d 1.5h     # 1 hour 30 minutes
zw journal track "Work" -d 2h30m    # 2 hours 30 minutes
zw journal track "Work" -d 1d       # 1 day (8 hours)
```

## Troubleshooting

### Config File Not Found

If the CLI can't find your config file:

```bash
mkdir -p ~/.config/zw
zw auth login
```

### Settings Not Applied

Make sure you:

1. Saved the file correctly
2. Using the right file path
3. Not overriding with command-line flags

Check your active config:

```bash
zw config show
```

### Reset to Defaults

Remove the config file and re-authenticate:

```bash
rm ~/.config/zw/config.yaml
zw auth login
```

***

For more help, use the built-in help system:

```bash
zw config --help
zw --help
```