Common Workflows

Common workflows and examples for the Zipwire CLI

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.

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

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

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

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

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

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

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

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

The CLI automatically creates journal entries from your git history, turning your development work into tracked time entries without manual data entry.

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

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

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

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

zw journal --help
zw timesheet --help
zw activity --help