# Common Workflows

These examples show how to use the Zipwire CLI for typical contractor workflows.

## Workflow 1: Daily Time Tracking

Track your work throughout the day and view what you've logged.

```bash
# Morning: Log your first task
zw journal track "Fixed authentication bug in login flow" -d 2h --activity "Client A > Development > Bug Fixes"

# Midday: Log another task
zw journal track "Code review for pull requests" -d 1h --activity "Client A > Development > Code Review"

# Afternoon: Log your final task
zw journal track "Documentation updates" -d 1.5h --activity "Client A > Documentation"

# End of day: Review what you tracked
zw journal list --today

# View summary of hours per activity
zw journal status
```

## Workflow 2: Create and Submit a Timesheet

Once you have entries in your journal, create a timesheet and send it for approval.

```bash
# Create a timesheet for the past week
zw timesheet create --from last-Monday --to today

# View the timesheet you just created
zw timesheet list --recent

# Verify the details
zw timesheet show --id <timesheet_id>

# Send it for approval (requires workflow to be configured)
zw timesheet send --id <timesheet_id>

# Check status
zw timesheet list --status pending
```

## Workflow 3: Manage Activities

Create and organize your project activities.

```bash
# Create a new client/project activity structure
zw activity create "Client A > Development > Features"
zw activity create "Client A > Development > Bug Fixes"
zw activity create "Client A > QA > Testing"

# Search for activities
zw activity search "Bug Fixes"

# View all activities in hierarchical format
zw activity list --style hierarchical

# View as flat list
zw activity list --style flat

# See recently used activities
zw activity recent
```

## Workflow 4: Automated Daily Tracking (Script)

Automate time tracking in a shell script. Useful for scheduled jobs or integrations.

```bash
#!/bin/bash
# daily_tracking.sh - Log time from git commits

API_TOKEN="zw_your_token"

# Get today's git commits and log them
git log --all --oneline --since="24 hours ago" | while read commit; do
  # Extract commit message
  msg=$(echo "$commit" | cut -d' ' -f2-)

  # Log to Zipwire (assumes 1 hour per commit)
  zw journal track "$msg" -d 1h --activity "My Company > Development > Coding"
done

echo "Daily time entries logged from git commits"
```

Run this daily:

```bash
# Make executable
chmod +x daily_tracking.sh

# Run manually
./daily_tracking.sh

# Or schedule with cron (runs daily at 5 PM)
# Add to crontab: 17 * * * * /path/to/daily_tracking.sh
```

## Workflow 5: Structured Output for Integration

Use structured output to integrate with other tools or scripts.

```bash
# Get recent entries as structured data
zw journal list --format structured --recent

# Parse with jq to get total hours
zw journal list --format structured --recent | \
  grep "DURATION" | \
  awk '{sum += $2} END {print "Total hours: " sum/60}'

# Export to CSV-like format
zw journal list --format structured | \
  grep -E "ACTIVITY|DESCRIPTION|DURATION" | \
  paste - - - | \
  sed 's/ACTIVITY: //;s/DESCRIPTION: //;s/DURATION: //'
```

## Workflow 6: Multiple Client Setup

Working for multiple clients? Create separate activity trees and track time accordingly.

```bash
# Create activities for each client
zw activity create "Client A > Development > Features"
zw activity create "Client A > Development > Support"
zw activity create "Client B > Design > UI/UX"
zw activity create "Client B > Development > Backend"

# Track time per client
zw journal track "Built new feature XYZ" -d 4h --activity "Client A > Development > Features"
zw journal track "Fixed production bug" -d 2h --activity "Client A > Development > Support"
zw journal track "Designed login flow" -d 3h --activity "Client B > Design > UI/UX"

# View hours per client
zw journal list --format structured | grep -E "ACTIVITY|DURATION"
```

## Workflow 7: Git Integration

Automatically log time when you push code or analyze your git history.

The CLI can parse your git commits and create time entries automatically:

```bash
#!/bin/bash
# daily_tracking.sh - Analyze git history and create journal entries

git log --all --oneline --since="24 hours ago" | while read commit; do
  msg=$(echo "$commit" | cut -d' ' -f2-)
  zw journal track "$msg" -d 1h --activity "My Company > Development > Coding"
done
```

Here's a real-world example of this in action:

<figure><img src="https://2043460614-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHxyMYVA40GzHDzjJfPrg%2Fuploads%2Fgit-blob-33aabbf4a32164e013ce48ba324a4ce3ccbaf3c3%2Fcli-git-tracking-example.png?alt=media" alt="Zipwire CLI tracking from git logs"><figcaption><p>The CLI automatically creates journal entries from your git history, turning your development work into tracked time entries without manual data entry.</p></figcaption></figure>

You can also hook into git events to automatically log time:

```bash
#!/bin/bash
# .git/hooks/post-push - Log time on git push

# This runs after you push to git
# Log a "code commit" entry
zw journal track "Pushed code changes to repository" \
  -d 30m \
  --activity "My Company > Development > Git Operations"

echo "Time logged for code push"
```

To set this up:

```bash
# Create hooks directory
mkdir -p .git/hooks

# Create and make executable
cat > .git/hooks/post-receive << 'EOF'
#!/bin/bash
zw journal track "Code pushed" -d 30m --activity "My Company > Development > Git Operations"
EOF

chmod +x .git/hooks/post-receive
```

## Workflow 8: Querying Your Data

Use structured output to query and analyze your time entries.

```bash
# List all entries and parse with jq
zw journal list --format structured | jq -r '.entries'

# Find all entries for a specific activity
zw journal list --format structured | \
  jq '.entries[] | select(.activity | contains("Bug Fixes"))'

# Calculate total time spent per activity
zw journal list --format structured | \
  jq -r '[.entries[] | {activity, duration}] | group_by(.activity) |
          map({activity: .[0].activity, total: (map(.duration) | add)})'
```

## Tips for Automation

1. **Store tokens securely**: Use environment variables, not hardcoded values
2. **Handle errors**: Check exit codes in scripts
3. **Use structured output**: Makes parsing and integration much easier
4. **Test first**: Run commands manually before automating them
5. **Log activities**: Keep records of what automation is doing
6. **Use cron carefully**: Schedule during off-hours if possible

## Next Steps

* Explore the full command reference with `zw --help`
* Set up a [Configuration](https://docs.zipwire.io/tools-and-integrations/configuration) that works for your workflow
* Integrate the CLI with your existing tools and CI/CD pipelines
* Consider how AI agents or coding assistants could help automate your time tracking

***

For detailed command documentation, use the built-in help:

```bash
zw journal --help
zw timesheet --help
zw activity --help
```