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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zipwire.io/tools-and-integrations/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.