Manage your Vtiger CRM
from the terminal

Quick Start

Install vtc with a single command. For manual installation or building from source, follow the instructions on the GitHub repository.

$ curl get.javanile.org/vtc | sh

Then connect to your Vtiger CRM in three simple steps.

$ vtc init

$ nano $(vtc config:file)

{
    "vtiger_url":  "https://yourcrm.example.com/vtigercrm/",
    "username":    "admin",
    "access_key":  "your-access-key-here"
}

$ vtc ping
{"success":true,"result":{"sessionName":"...","userId":"19x1"}}

Multiple CRM

The CRM environment variable is the most powerful feature of vtc. It lets you manage multiple Vtiger instances from the same terminal without switching directories.

How it works

When you set the CRM variable, vtc reads configuration from ~/.vtc/<name>/vtiger.config.json instead of the current directory.

Setting up multiple CRM instances

$ CRM=production    vtc init
$ CRM=staging       vtc init
$ CRM=client-mumbai vtc init

$ nano $(CRM=production vtc config:file)
$ nano $(CRM=staging vtc config:file)
$ nano $(CRM=client-mumbai vtc config:file)

$ CRM=production    vtc ping
$ CRM=staging       vtc ping
$ CRM=client-mumbai vtc ping

Listing all configured instances

Use vtc crm-list to see all your configured CRM instances at a glance:

$ vtc crm-list

Using CRM in daily work

Every vtc command respects the CRM variable. Just prefix it:

# Query contacts on production
$ CRM=production vtc query "SELECT * FROM Contacts LIMIT 10"

# Describe module on staging
$ CRM=staging vtc describe Accounts

# Retrieve a record from client instance
$ CRM=client-mumbai vtc retrieve 12x1020

Export for the entire session

If you're working on one instance for a while, export it once:

$ export CRM=production
$ vtc ping                              # uses production
$ vtc query "SELECT * FROM Leads"        # uses production
$ vtc describe Contacts                  # uses production

# Switch back to local config:
$ unset CRM

Shell aliases for quick access

Add these to your .bashrc or .zshrc for faster workflows:

# Add to ~/.bashrc or ~/.zshrc
alias vtc-prod='CRM=production vtc'
alias vtc-stag='CRM=staging vtc'
alias vtc-mum='CRM=client-mumbai vtc'

Then use them directly:

$ vtc-prod query "SELECT * FROM Accounts"
$ vtc-stag describe Leads
$ vtc-mum ping

Command Reference

Complete list of all available vtc commands with usage examples.

$ vtc init                        # in current directory
$ CRM=mycrm vtc init              # in ~/.vtc/mycrm/

$ vtc ping
$ CRM=production vtc ping

$ vtc config:dir
/home/user/myproject

$ CRM=production vtc config:dir
/home/user/.vtc/production

$ nano $(vtc config:file)
$ nano $(CRM=production vtc config:file)

$ vtc crm-list
NAME          URL
------------------------------------------
(local)       https://demo.vtiger.com/vtigercrm/
production    https://crm.example.com/vtigercrm/
staging       https://staging.example.com/vtigercrm/

# Fetch all contacts
$ vtc query "SELECT * FROM Contacts"

# With filters
$ vtc query "SELECT firstname, lastname FROM Contacts WHERE lastname = 'Sharma'"

# With LIMIT
$ vtc query "SELECT * FROM Leads LIMIT 20"

# Accounts by industry
$ vtc query "SELECT accountname, phone FROM Accounts WHERE industry = 'IT Services'"

$ vtc listtypes

# Basic module structure
$ vtc describe Contacts

# With reference resolution
$ vtc describe Contacts 1
$ vtc describe Contacts 2

$ vtc retrieve 12x1020
$ vtc retrieve 12x1020 1    # with depth

# Inline JSON
$ vtc create Contacts '{"firstname":"Ravi","lastname":"Kumar","email":"ravi@example.com"}'

# From JSON file
$ vtc create Contacts @contact.json

# Inline JSON with id
$ vtc update Contacts '{"id":"12x1020","phone":"+91 22 12345678"}'

# From file
$ vtc update Contacts @update.json

# With separate id and file
$ vtc update Contacts 12x1020 @data.json

# From file
$ vtc revise Contacts @revision.json

# Single field update
$ vtc revise Contacts 12x1020 phone "+91 22 9999999"

# With separate id and file
$ vtc revise Contacts 12x1020 @partial.json

Recipes & Use Cases

Practical examples for common workflows.

#!/bin/bash
for crm in production staging; do
  echo "=== $crm ==="
  CRM=$crm vtc ping
  echo
done

$ CRM=production vtc query \
  "SELECT * FROM Contacts" \
  > contacts.json

# Pipe to jq for formatting
$ CRM=production vtc query \
  "SELECT * FROM Leads" \
  | jq '.result'

# crontab -e
0 */6 * * * CRM=production \
  /usr/local/bin/vtc query \
  "SELECT * FROM Leads \
  WHERE createdtime > '2024-01-01'" \
  >> /var/log/crm-leads.json

# In your CI script
export CRM=test
vtc ping || exit 1
vtc listtypes
echo "CRM connection verified"

# Create contact.json with your data
$ CRM=production vtc create \
  Contacts @contact.json

# Loop over multiple files
for f in records/*.json; do
  CRM=production vtc create Leads @$f
done

# List all modules
$ vtc listtypes | jq '.result.types'

# Get field details
$ vtc describe Accounts \
  | jq '.result.fields[].name'

Configuration

The vtiger.config.json file contains everything needed to connect to a Vtiger instance.

{
    "vtiger_url":  "https://crm.example.com/vtigercrm/",
    "username":    "admin",
    "access_key":  "your-access-key-here"
}

Where to find the Access Key

In Vtiger CRM, navigate to My Preferences (user icon at the top-right corner). Scroll down to the User Advanced Options section and copy the Access Key value.

Requirements

Need Help?

We are here to help you. If you have questions, found a bug, or need assistance with vtc, the best way to get support is by opening an issue on our GitHub repository.

Our team actively monitors issues and will respond as soon as possible. When opening an issue, please include:

• A clear description of your problem or question
• The vtc command you ran and the output you received
• Your PHP version and operating system