ACRM CLI

Manage your ACRM contacts, organizations, tasks, and pipelines from your terminal.

Installation

You need Node.js 22.12 or later, with npm installed.

npm install --global @sunnygg/acrm-cli
acrm --help

To update, run the same installation command again.

Get an API key

1. Sign in to ACRM and open API keys.
2. Enter a key name, such as My terminal, and choose an expiration period.
3. Select Generate API key and copy the key. You can only view it once.
4. Run the following command and paste your key when prompted:

acrm auth login

Your input is hidden, and the CLI saves the key for future commands. To replace it, run acrm auth login again. You can revoke keys from the API keys page.

Usage

Choose a workspace

List your workspaces. This also checks that your API key works:

acrm get workspace

Copy the ID of the workspace you want to use. In Bash or Zsh, set it for your current terminal session:

export ACRM_WORKSPACE_ID=YOUR_WORKSPACE_ID

Replace YOUR_WORKSPACE_ID with the ID you copied. If you don't have a workspace yet, create one with acrm create workspace and follow the prompts.

You can also choose a workspace for a single command:

acrm get person --workspace YOUR_WORKSPACE_ID

Add your first contact

Run this command and follow the prompts:

acrm create person

Then list your contacts:

acrm get person

View and update a contact

Use an ID from the contact list wherever you see PERSON_ID below.

acrm get person PERSON_ID
acrm update person PERSON_ID

The update command prompts you to choose which fields to change. Fields you leave out keep their existing values.

For help with any command, add --help:

acrm --help
acrm create person --help
acrm search task --help

Do more when you're ready

Expand a topic for examples and options. Replace IDs such as PERSON_ID and TASK_ID with IDs from your own workspace.

Supply fields directly when you already know what you want to enter:

acrm create person --name "Jane Doe" --email [email protected]
acrm update person PERSON_ID --phone "+1 555 010 0123"
acrm update person PERSON_ID --email null

null clears a field that allows an empty value. When you supply field options, there are no follow-up prompts, so include all required fields when creating an item. Use --help to see the fields available for each command.

To permanently delete a contact:

acrm delete person PERSON_ID

Deletion happens immediately, without a confirmation prompt. Deleting a workspace also deletes its CRM data.

The same create, get, update, and delete commands work with these items:

| Item | Command name | | --- | --- | | Workspaces | workspace | | People | person | | Organizations | organization | | Links between people and organizations | relationship | | Pipelines | pipeline | | Pipeline stages | stage | | Records | record | | Interactions | interaction | | Tasks | task |

For example, create an organization, link a contact to it, and add a task:

acrm create organization --name "Example Co" --domain example.com
acrm create relationship --person-id PERSON_ID --organization-id ORGANIZATION_ID
acrm create task --title "Call Jane" --person-id PERSON_ID
acrm update task TASK_ID --completed true

Boolean fields such as --completed take an explicit true or false.

For items with more fields, start with the guided prompts:

acrm create pipeline
acrm create stage
acrm create record

Plural names also work: for example, acrm get people is equivalent to acrm get person. You can use list in place of get.

Search contacts by text, sort results, or show only active items:

acrm get person --search "Jane"
acrm get person --sort name --direction asc --archived active
acrm get person --columns id,name,email

Use search for specific fields and relationships:

acrm search person --email [email protected]
acrm search person --organization-id ORGANIZATION_ID
acrm search task --completed false
acrm search record --status open --without-next-action true

Multiple search filters must all match. search shows active items by default; add --include-archived to include archived items. get includes archived items unless you specify --archived active or --archived archived.

Lists may contain only one page. Add --all to fetch every page, or use --limit to set a page size from 1 to 100:

acrm get person --all
acrm get person --search "Jane" --limit 25

Add --json to a read command for machine-readable output. For example, export all contacts to a file:

acrm get person --all --json > contacts.json

This saves the full response, including its items array and pagination fields. To import data, supply an object or an array of objects containing writable fields. An exported response is not directly importable.

For example, save this as people.json:

[
  {"name": "Jane Doe", "email": "[email protected]"},
  {"name": "Alex Smith", "email": "[email protected]"}
]

Then import it:

acrm create person --json @people.json --delay 650

For create and update, --json takes inline JSON, @filename, or - to read from stdin, and also returns JSON output:

acrm update person PERSON_ID --json '{"email":null}'
cat people.json | acrm create person --json - --delay 650

JSON field names use underscores, such as person_id; command options use hyphens, such as --person-id. Do not mix field options with --json. To use field options and still get JSON output, add --output-json:

acrm create person --name "Jane Doe" --output-json

Bulk updates take an array with an id on each object:

[
  {"id": "PERSON_ID", "name": "Jane Smith"},
  {"id": "ANOTHER_PERSON_ID", "email": null}
]

acrm update person --json @updates.json --delay 650

Imports and bulk updates save items one at a time. If an item fails, the command stops and earlier changes remain saved. The output reports completed items and the failed item's index, starting at zero. Check those results before retrying; after a timeout, check ACRM too, because the last item may have been saved. --delay 650 adds a 650 ms pause between writes to help stay within rate limits.

View changes to a contact:

acrm get history --resource-type people --resource-id PERSON_ID --all

Discover additional operations, such as workspace briefings, archiving, restoring items, and moving records between stages:

acrm tools

Inspect an operation's description and accepted inputs before using it:

acrm tools get_person_context --json
acrm tool get_person_context --arg person_id=PERSON_ID

The CLI uses your selected workspace when the operation accepts a workspace ID.

For scripts, supply your API key through ACRM_API_KEY and your workspace through ACRM_WORKSPACE_ID. Use field options or JSON input to avoid interactive prompts.

| Setting | Environment variable | Command option | | --- | --- | --- | | API key | ACRM_API_KEY | --api-key | | Workspace ID | ACRM_WORKSPACE_ID | --workspace | | Request timeout in milliseconds | ACRM_TIMEOUT_MS | --timeout |

Command options override environment variables. For API keys, both override the saved login. The default request timeout is 30,000 ms.

Saved keys are stored in plaintext at ~/.config/acrm/credentials.json, or $XDG_CONFIG_HOME/acrm/credentials.json if XDG_CONFIG_HOME is set, with owner-only file permissions on Unix.

For scripts, exit codes are 0 for success, 1 for input or request failures, 2 for command syntax errors, and 130 for cancelled prompts. JSON-mode errors are written to stderr; failed bulk operations also write their progress to stdout.