CLI Commands Reference

Magento FreeAgent Integration provides a comprehensive set of CLI commands for managing synchronization, testing, and system maintenance. This reference covers all available commands organized by functionality.

Quick Reference

# Contact Sync
bin/magento fa_contact:collect          # Fetch contacts from FreeAgent
bin/magento fa_contact:export           # Export customers to FreeAgent
bin/magento fa_contact:import           # Import contacts from FreeAgent

# Invoice Sync
bin/magento fa_invoice:collect          # Fetch invoices from FreeAgent
bin/magento fa_invoice:export           # Export orders as invoices
bin/magento fa_invoice:import           # Import invoice status

# Credit Memo Sync
bin/magento fa_creditmemo:collect       # Fetch credit memos from FreeAgent
bin/magento fa_creditmemo:export        # Export credit memos
bin/magento fa_creditmemo:import        # Import credit memo status

# Profile Management
bin/magento profile:config:export       # Export profile configuration
bin/magento profile:config:import       # Import profile configuration
bin/magento profile:data:purge          # Purge profile history data

# Notifications
bin/magento notification:send:emails    # Send pending notification emails

Contact Commands

fa_contact:collect

Fetch contact data from FreeAgent API and store locally for processing.

bin/magento fa_contact:collect

What it does:

Connects to FreeAgent API
Retrieves contact records
Stores data in freeagent_contact_entity table
Updates collected_at timestamp

Options:

Option	Short	Type	Description
`--profile`	`-p`	INT	Filter by profile ID
`--id`	`-i`	INT	Filter by entity ID
`--status`	`-s`	STRING	Filter by status

Example:

# Collect all contacts
bin/magento fa_contact:collect

# Collect for a specific profile
bin/magento fa_contact:collect --profile=1

fa_contact:export

Export Magento customers to FreeAgent as contacts.

bin/magento fa_contact:export [options]

What it does:

Retrieves Magento customers pending export
Generates FreeAgent contact payloads
Creates or updates contacts via FreeAgent API
Updates sync status and queue

Options:

Option	Short	Type	Description
`--profile`	`-p`	INT	Filter by profile ID
`--id`	`-i`	INT	Filter by entity ID
`--status`	`-s`	STRING	Filter by status
`--dry-run`		FLAG	Preview without sending to API

Examples:

# Export all pending contacts
bin/magento fa_contact:export

# Export specific contact
bin/magento fa_contact:export --id=42

# Preview export without sending
bin/magento fa_contact:export --dry-run

# Export for specific profile
bin/magento fa_contact:export --profile=1

Example output:

FreeAgent Contact Export
========================

Processing 15 contacts...

 15/15 [============================] 100%

Results:
  Created: 12
  Updated: 3
  Errors:  0

Export completed successfully.

fa_contact:import

Import contact data from FreeAgent and update Magento entities.

bin/magento fa_contact:import [options]

Options:

Option	Short	Type	Description
`--profile`	`-p`	INT	Filter by profile ID
`--id`	`-i`	INT	Filter by entity ID
`--status`	`-s`	STRING	Filter by status

Example:

# Import all pending contacts
bin/magento fa_contact:import

Invoice Commands

fa_invoice:collect

Fetch invoice data from FreeAgent API.

bin/magento fa_invoice:collect [options]

What it does:

Connects to FreeAgent API
Retrieves invoice records
Stores data in freeagent_invoice_entity table
Updates collected_at timestamp

Options:

Option	Short	Type	Description
`--profile`	`-p`	INT	Filter by profile ID
`--id`	`-i`	INT	Filter by entity ID
`--status`	`-s`	STRING	Filter by status

fa_invoice:export

Export Magento orders to FreeAgent as invoices.

bin/magento fa_invoice:export [options]

What it does:

Retrieves Magento orders pending export
Creates/links FreeAgent contacts for order customers
Generates FreeAgent invoice payloads (line items, shipping, discounts, tax)
Creates or updates invoices via FreeAgent API
Optionally triggers invoice email delivery
Updates sync status, order history, and queue

Options:

Option	Short	Type	Description
`--profile`	`-p`	INT	Filter by profile ID
`--id`	`-i`	INT	Filter by entity ID
`--status`	`-s`	STRING	Filter by status
`--dry-run`		FLAG	Preview without sending to API

Examples:

# Export all pending orders as invoices
bin/magento fa_invoice:export

# Export specific order
bin/magento fa_invoice:export --id=100001234

# Preview export without creating invoices
bin/magento fa_invoice:export --dry-run

# Export for specific profile
bin/magento fa_invoice:export --profile=1

Example output:

FreeAgent Invoice Export
========================

Processing 8 orders...

 8/8 [============================] 100%

Results:
  Created:  6
  Updated:  2
  Contacts: 5 created, 3 linked
  Errors:   0

Export completed successfully.

fa_invoice:import

Import invoice status and data from FreeAgent.

bin/magento fa_invoice:import [options]

What it does:

Processes collected FreeAgent invoice data
Updates Magento order status based on FreeAgent invoice status
Syncs payment information

Options:

Option	Short	Type	Description
`--profile`	`-p`	INT	Filter by profile ID
`--id`	`-i`	INT	Filter by entity ID
`--status`	`-s`	STRING	Filter by status

Credit Memo Commands

fa_creditmemo:collect

Fetch credit memo data from FreeAgent API.

bin/magento fa_creditmemo:collect [options]

Options:

Option	Short	Type	Description
`--profile`	`-p`	INT	Filter by profile ID
`--id`	`-i`	INT	Filter by entity ID
`--status`	`-s`	STRING	Filter by status

fa_creditmemo:export

Export Magento credit memos to FreeAgent as credit notes.

bin/magento fa_creditmemo:export [options]

What it does:

Retrieves Magento credit memos pending export
Creates/links FreeAgent contacts for credit memo customers
Generates FreeAgent credit note payloads (line items, shipping refunds, tax)
Creates or updates credit notes via FreeAgent API
Optionally triggers credit note email delivery
Updates sync status and queue

Options:

Option	Short	Type	Description
`--profile`	`-p`	INT	Filter by profile ID
`--id`	`-i`	INT	Filter by entity ID
`--status`	`-s`	STRING	Filter by status
`--dry-run`		FLAG	Preview without sending to API

Examples:

# Export all pending credit memos
bin/magento fa_creditmemo:export

# Export specific credit memo
bin/magento fa_creditmemo:export --id=42

# Preview export
bin/magento fa_creditmemo:export --dry-run

fa_creditmemo:import

Import credit memo status from FreeAgent.

bin/magento fa_creditmemo:import [options]

Options:

Option	Short	Type	Description
`--profile`	`-p`	INT	Filter by profile ID
`--id`	`-i`	INT	Filter by entity ID
`--status`	`-s`	STRING	Filter by status

Profile Management Commands

profile:config:export

Export profile configuration data for backup or migration.

bin/magento profile:config:export

What it does:

Exports all profile configurations
Outputs configuration data for backup
Useful for migrating between environments

Use Cases:

Backing up profile configuration before changes
Migrating configuration from staging to production
Sharing configuration between team members

profile:config:import

Import profile configuration data.

bin/magento profile:config:import

What it does:

Imports profile configuration from exported data
Restores or creates profiles with specified settings

profile:data:purge

Purge old profile history and data.

bin/magento profile:data:purge

What it does:

Removes old profile execution history
Cleans up queue records
Respects the configured history lifetime setting

Regular Maintenance

Run this command periodically or rely on the built-in cron job (byte8_profile_queue_cleanup) that runs daily at 2:15 AM.

Notification Commands

notification:send:emails

Send pending notification emails.

bin/magento notification:send:emails

What it does:

Processes pending notification queue
Sends batch email summaries
Marks notifications as emailed

Automatic Processing

This command runs automatically via cron (byte8_notification_send_batch_emails) every 15 minutes when notifications are enabled.

Common Patterns

Dry Run Testing

Before running any export in production, use --dry-run to preview:

# Preview contact export
bin/magento fa_contact:export --dry-run

# Preview invoice export
bin/magento fa_invoice:export --dry-run

# Preview credit memo export
bin/magento fa_creditmemo:export --dry-run

Full Sync Workflow

Execute a complete synchronization cycle:

# Step 1: Export contacts
bin/magento fa_contact:export

# Step 2: Export invoices (contacts must exist first)
bin/magento fa_invoice:export

# Step 3: Export credit memos
bin/magento fa_creditmemo:export

# Step 4: Collect data from FreeAgent
bin/magento fa_invoice:collect
bin/magento fa_creditmemo:collect

# Step 5: Import status updates
bin/magento fa_invoice:import
bin/magento fa_creditmemo:import

Debugging a Specific Entity

When troubleshooting a specific order or customer:

# Check contact sync for specific customer
bin/magento fa_contact:export --id=42 --dry-run

# Check invoice sync for specific order
bin/magento fa_invoice:export --id=100001234 --dry-run

# Review logs after running
tail -f var/log/freeagent/contact.log
tail -f var/log/freeagent/invoice.log
tail -f var/log/freeagent/creditmemo.log

Maintenance Tasks

Regular maintenance commands:

# Purge old profile data
bin/magento profile:data:purge

# Flush Magento cache
bin/magento cache:flush

# Check cron status
bin/magento cron:run --group=default

Log Files

All CLI commands write to the following log files for debugging:

Log File	Content
`var/log/freeagent/client.log`	Core API client, OAuth tokens
`var/log/freeagent/contact.log`	Contact sync operations
`var/log/freeagent/invoice.log`	Invoice sync operations
`var/log/freeagent/creditmemo.log`	Credit memo sync operations
`var/log/byte8/debug.log`	Core framework debug
`var/log/byte8/scheduler.log`	Profile scheduling

Quick Reference​

Contact Commands​

fa_contact:collect​

fa_contact:export​

fa_contact:import​

Invoice Commands​

fa_invoice:collect​

fa_invoice:export​

fa_invoice:import​

Credit Memo Commands​

fa_creditmemo:collect​

fa_creditmemo:export​

fa_creditmemo:import​

Profile Management Commands​

profile:config:export​

profile:config:import​

profile:data:purge​

Notification Commands​

notification:send:emails​

Common Patterns​

Dry Run Testing​

Full Sync Workflow​

Debugging a Specific Entity​

Maintenance Tasks​

Log Files​

Related Documentation​

Quick Reference

Contact Commands

fa_contact:collect

fa_contact:export

fa_contact:import

Invoice Commands

fa_invoice:collect

fa_invoice:export

fa_invoice:import

Credit Memo Commands

fa_creditmemo:collect

fa_creditmemo:export

fa_creditmemo:import

Profile Management Commands

profile:config:export

profile:config:import

profile:data:purge

Notification Commands

notification:send:emails

Common Patterns

Dry Run Testing

Full Sync Workflow

Debugging a Specific Entity

Maintenance Tasks

Log Files

Related Documentation