Configuration

Configuring the Zipwire CLI for your workflow

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:

~/.config/zw/config.yaml

To view your current configuration:

zw config show

Configuration Options

API Settings

api-base-url

The API endpoint the CLI connects to.

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.

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.

output-format: human

Options:

• human – Pretty-printed, hierarchical output with colors (default)

• structured – Machine-readable key-value format

Override per-command:

zw activity list --format structured

no-color

Disable colored output.

no-color: false

Options:

• false – Colors enabled (default)

• true – Disable all colors

Override per-command:

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:

zw config set output-format structured
zw config show

Manual Editing

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

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:

# 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:

#!/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:

# 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:

zw journal track --help

Multiple Configurations

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

# 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:

# ❌ Wrong
zw journal track Work on bug > Development

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

Dates

Dates are parsed intelligently:

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:

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:

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:

zw config show

Reset to Defaults

Remove the config file and re-authenticate:

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

---

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

zw config --help
zw --help