ImmyBot - Printing Press CLI

Prerequisites: Install the CLI

This skill drives the immybot-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

macOS / Linux:

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/immybot/install.sh)

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/immybot/install.ps1 | iex

Verify: immybot-cli --version
Ensure ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows) is on $PATH.

The installer downloads the immybot-cli and immybot-mcp binaries into ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows). It does not register the skill with your agent and writes no MCP client config - see mcp-install.md for that wire-up.

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

ImmyBot's API is large and entirely per-tenant, so the questions MSPs actually ask span calls the web UI never joins. This CLI types the whole surface, mirrors it into local SQLite with full-text search, and adds commands built on that mirror: session-triage collapses a night of failures into distinct root causes, version-spread ranks one software title across every tenant with a real semver comparator, and assignment-explain shows which deployment rule actually won on a given machine.

When to Use This CLI

Use this CLI for any ImmyBot question that spans more than one tenant, or that needs history the API does not keep. It is the right tool for post-maintenance triage, cross-tenant software version audits, working out why a deployment did or did not land on a machine, and reconciling ImmyBot against a linked PSA or RMM. It is also the fastest way to script against the full ImmyBot surface, since every endpoint is typed and every command speaks JSON.

Anti-triggers

Do not use this CLI for:

Do not use this CLI to remote-control a user's desktop; ImmyBot's own remote control session is a browser workflow and this CLI only returns the screen-share URL.
Do not use this CLI to author or debug PowerShell script content; it manages script records and execution history, not the script editor experience.
Do not use this CLI as a live monitoring dashboard; cross-tenant commands read a local mirror that is only as fresh as the last sync.
Do not use this CLI to configure Entra ID app registrations or ImmyBot user permissions for the first time; that setup is a portal workflow.

Unique Capabilities

These capabilities aren't available in any other tool for this API.

Local state that compounds

session-triage - Group last night's failed maintenance actions by root cause instead of reading the same error on forty machines.

Reach for this first after any maintenance window: it turns N red machines into the handful of distinct problems actually worth a ticket.
```
immybot-cli session-triage --since 24h --agent
```
version-spread - Semver-ordered distribution of one software title across every tenant, flagging everything below a floor.

This is the CVE-response command: one call answers which clients are still exposed on a given title.
```
immybot-cli version-spread "Google Chrome" --min-version 140 --agent
```
fleet-diff - What actually changed between two syncs: computers added or removed, software versions moved, assignments modified. Requires a local baseline: run fleet-diff --snapshot after a sync to record one (there is no updated-since cursor in the API), then compare with --since.

Use this to answer "what changed since last night" without diffing two exports by hand.
```
immybot-cli fleet-diff --since 24h --agent
```
onboarding-stalled - Computers stuck waiting to onboard, bucketed by age and annotated with whether onboarding was ever attempted.

Surfaces machines that silently never finished onboarding, which is the failure mode clients notice first.
```
immybot-cli onboarding-stalled --older-than 3d --agent
```

Deployment resolution

assignment-explain - Show every target assignment that resolves onto one computer, which scope matched, and which rules are shadowed.

Use this for any "why didn't this machine get X" question; it answers what a computer receives and why, which no single endpoint does.
```
immybot-cli assignment-explain 4821 --agent
```
script-blast-radius - Every maintenance task, software package, and computer that a script reaches before you edit it.

Run this before editing any shared script; it is the only way to see downstream reach across tenants.
```
immybot-cli script-blast-radius 312 --agent
```

Integration hygiene

psa-reconcile - Diff the ImmyBot roster against a linked PSA or RMM asset roster to find unlinked computers and orphaned assets.

Run after each week of onboards and decommissions; mapping gaps otherwise surface as a wrong invoice or a machine that stopped getting maintenance.
```
immybot-cli psa-reconcile --provider 7 --agent
```

Command Reference

access - Manage access

immybot-cli access create-delete-azure-tenant-auth-details - Create delete azure tenant auth details
immybot-cli access create-request - Create request
immybot-cli access create-update-azure-tenant-auth-details - Create update azure tenant auth details
immybot-cli access get-get-azure-tenant-auth-details-by-azure-tenant-principal-id - Get get azure tenant auth details by azure tenant principal id
immybot-cli access get-get-ip-addresses - Get get ip addresses
immybot-cli access get-me-permissions-by-permission-type-tenants - Get me permissions by permission type tenants
immybot-cli access list - List

application-locks - Manage application locks

immybot-cli application-locks create-request-cancellation - Create request cancellation
immybot-cli application-locks get-realtime-event-stream - Get realtime event stream
immybot-cli application-locks list - List

application-logs - Manage application logs

immybot-cli application-logs create-source-context - Create source context
immybot-cli application-logs create-source-context-clear - Create source context clear
immybot-cli application-logs create-source-context-clear-all - Create source context clear all
immybot-cli application-logs create-streaming - Create streaming
immybot-cli application-logs get-source-contexts - Get source contexts

audits - Manage audits

immybot-cli audits get-global-dx - Get global dx
immybot-cli audits get-local-dx - Get local dx

azure - Manage azure

immybot-cli azure create-disambiguate-tenant-type - Create disambiguate tenant type
immybot-cli azure create-preconsent-customer-tenants - Create preconsent customer tenants
immybot-cli azure create-sync-details-from-tenants - Create sync details from tenants
immybot-cli azure create-sync-users-from-tenants - Create sync users from tenants
immybot-cli azure create-tenant-consented - Create tenant consented
immybot-cli azure get-app-registration-options - Get app registration options
immybot-cli azure get-partner-tenant-customers-by-partner-principal-id - Get partner tenant customers by partner principal id
immybot-cli azure get-partner-tenant-infos - Get partner tenant infos

azure-errors - Manage azure errors

immybot-cli azure-errors get-dx - Get dx
immybot-cli azure-errors get-for-tenant-by-tenant-principal-id-dx - Get for tenant by tenant principal id dx

billing - Manage billing

immybot-cli billing create-cancel-subscription - Create cancel subscription
immybot-cli billing create-information - Create information
immybot-cli billing create-reactivate-subscription - Create reactivate subscription
immybot-cli billing create-update-addon - Create update addon
immybot-cli billing create-update-subscription - Create update subscription
immybot-cli billing get-credit-cards - Get credit cards
immybot-cli billing get-download-invoice - Get download invoice
immybot-cli billing get-feature-usage-counts - Get feature usage counts
immybot-cli billing get-information - Get information
immybot-cli billing get-platform-details - Get platform details
immybot-cli billing get-product-catalog - Get product catalog
immybot-cli billing get-product-catalog-items - Get product catalog items
immybot-cli billing get-subscription-details - Get subscription details

brandings - Manage brandings

immybot-cli brandings create - Create
immybot-cli brandings create-global-default-by-id - Create global default by id
immybot-cli brandings create-send-test-email - Create send test email
immybot-cli brandings create-validate-time-format-by-time-format - Create validate time format by time format
immybot-cli brandings delete-by-id - Delete by id
immybot-cli brandings get-by-id - Get by id
immybot-cli brandings get-support - Fetches support related branding changes to be used in the Support Sidebar, Session Support Request
immybot-cli brandings list - List
immybot-cli brandings update-by-id - Update by id

change-requests - Manage change requests

immybot-cli change-requests delete-by-id - Delete by id
immybot-cli change-requests get-dx - Get dx
immybot-cli change-requests get-open-count - Get open count

chocolatey - Manage chocolatey

immybot-cli chocolatey get-find-packages-by-id - Get find packages by id
immybot-cli chocolatey get-search - Get search

computers - Manage computers

immybot-cli computers create-add-tags - Create add tags
immybot-cli computers create-bulk-delete - Create bulk delete
immybot-cli computers create-change-tenant - Create change tenant
immybot-cli computers create-remove-tags - Create remove tags
immybot-cli computers create-restore - Create restore
immybot-cli computers create-set-excluded-from-user-affinity - Create set excluded from user affinity
immybot-cli computers create-skip-onboarding - Create skip onboarding
immybot-cli computers get-agent-status - Get agent status
immybot-cli computers get-by-id - Get by id
immybot-cli computers get-dx - Get dx
immybot-cli computers get-export - Get export
immybot-cli computers get-inventory - Get inventory
immybot-cli computers get-inventory-export - Get inventory export
immybot-cli computers get-inventory-software-search-by-name - Get inventory software search by name
immybot-cli computers get-inventory-software-search-by-upgrade-code - Get inventory software search by upgrade code
immybot-cli computers get-my - Get my
immybot-cli computers get-onboarding - Get onboarding
immybot-cli computers get-paged - List computers with server-side paging, filtering, and sorting (skip/take)
immybot-cli computers get-user-affinities - Get user affinities
immybot-cli computers get-user-affinities-export - Get user affinities export
immybot-cli computers list - List
immybot-cli computers update-by-id - Update by id

dynamic-provider-types - Manage dynamic provider types

immybot-cli dynamic-provider-types create-global - Create global
immybot-cli dynamic-provider-types create-global-by-id - Create global by id
immybot-cli dynamic-provider-types create-global-by-id-reload - Create global by id reload
immybot-cli dynamic-provider-types create-local - Create local
immybot-cli dynamic-provider-types create-local-by-id - Create local by id
immybot-cli dynamic-provider-types create-local-by-id-reload - Create local by id reload
immybot-cli dynamic-provider-types create-reload - Create reload
immybot-cli dynamic-provider-types create-test-environment-by-terminal-id - Create test environment by terminal id
immybot-cli dynamic-provider-types create-test-environment-by-terminal-id-bind-configuration-form - Create test environment by terminal id bind configuration form
immybot-cli dynamic-provider-types create-test-environment-by-terminal-id-execute-method-by-method - Create test environment by terminal id execute method by method
immybot-cli dynamic-provider-types delete-global-by-id - Delete global by id
immybot-cli dynamic-provider-types delete-local-by-id - Delete local by id
immybot-cli dynamic-provider-types delete-test-environment-by-terminal-id - Delete test environment by terminal id
immybot-cli dynamic-provider-types get-global-by-id - Get global by id
immybot-cli dynamic-provider-types get-local-by-id - Get local by id
immybot-cli dynamic-provider-types list - List

effective-permissions - Manage effective permissions

immybot-cli effective-permissions create-groups-by-group-id-evaluate-all-assignments - Returns all role assignments for a group grouped by permission without evaluation context.
immybot-cli effective-permissions create-groups-by-group-id-evaluate-resource - Evaluates permissions for a group against a specific resource.
immybot-cli effective-permissions create-groups-by-group-id-evaluate-tenant - Evaluates permissions for a group against a specific tenant.
immybot-cli effective-permissions create-users-by-user-id-evaluate-all-assignments - Returns all role assignments for a user grouped by permission without evaluation context.
immybot-cli effective-permissions create-users-by-user-id-evaluate-resource - Evaluates permissions for a user against a specific resource.
immybot-cli effective-permissions create-users-by-user-id-evaluate-tenant - Evaluates permissions for a user against a specific tenant.

ephemeral-session - Manage ephemeral session

immybot-cli ephemeral-session get-by-agent-instance-id-by-provider-agent-id - Get by agent instance id by provider agent id
immybot-cli ephemeral-session get-development-latest-ephemeral-binary - Get development latest ephemeral binary
immybot-cli ephemeral-session get-development-latest-ephemeral-binary-v2 - Get development latest ephemeral binary v2

getting-started - Manage getting started

immybot-cli getting-started create-checklist-complete - Create checklist complete
immybot-cli getting-started create-checklist-reset - Create checklist reset
immybot-cli getting-started get-checklist - Get checklist

groups - Manage groups

immybot-cli groups create - Create
immybot-cli groups delete-by-id - Delete by id
immybot-cli groups get-by-id - Get by id
immybot-cli groups list - List
immybot-cli groups update-by-id - Update by id

immy-agent-metadata - Manage immy agent metadata

immybot-cli immy-agent-metadata - Get agent hash

installer - Manage installer

immybot-cli installer - Create agent rekey request

inventory-tasks - Manage inventory tasks

immybot-cli inventory-tasks create-local - Create local
immybot-cli inventory-tasks create-local-by-id - Create local by id
immybot-cli inventory-tasks create-local-by-id-scripts - Create local by id scripts
immybot-cli inventory-tasks delete-local-by-id - Delete local by id
immybot-cli inventory-tasks delete-local-by-task-id-scripts-by-inventory-key - Delete local by task id scripts by inventory key
immybot-cli inventory-tasks list - List

licenses - Manage licenses

immybot-cli licenses create - Create
immybot-cli licenses create-upload - Create upload
immybot-cli licenses delete-by-id - Delete by id
immybot-cli licenses get-by-id - Get by id
immybot-cli licenses get-dx - Get dx
immybot-cli licenses list - List
immybot-cli licenses update-by-id - Update by id

maintenance-actions - Manage maintenance actions

immybot-cli maintenance-actions create-latest-action-for-computers - Create latest action for computers
immybot-cli maintenance-actions create-latest-action-for-tenants - Create latest action for tenants
immybot-cli maintenance-actions get-computer-by-computer-id-needs-attention - Get computer by computer id needs attention
immybot-cli maintenance-actions get-dx - Get dx
immybot-cli maintenance-actions get-dx-for-computer-by-computer-id - Get dx for computer by computer id
immybot-cli maintenance-actions get-latest-for-computer-by-computer-id - Get latest for computer by computer id
immybot-cli maintenance-actions get-latest-for-tenant-by-tenant-id - Get latest for tenant by tenant id
immybot-cli maintenance-actions get-latest-non-compliant-actions-for-tenant-by-tenant-id - Get latest non compliant actions for tenant by tenant id
immybot-cli maintenance-actions get-maintenance-item - Get maintenance item
immybot-cli maintenance-actions get-version - Get version

maintenance-emails - Manage maintenance emails

maintenance-sessions - Manage maintenance sessions

immybot-cli maintenance-sessions create-cancel - Create cancel
immybot-cli maintenance-sessions create-cancel-all - Create cancel all
immybot-cli maintenance-sessions create-rerun-v2 - Create rerun v2
immybot-cli maintenance-sessions get-by-session-id - Get by session id
immybot-cli maintenance-sessions get-cancel-for-schedule-by-schedule-id - Get cancel for schedule by schedule id
immybot-cli maintenance-sessions get-dx - Get dx
immybot-cli maintenance-sessions get-status-counts - Get status counts

maintenance-tasks - Manage maintenance tasks

immybot-cli maintenance-tasks create-duplicate - Create duplicate
immybot-cli maintenance-tasks create-global - Create global
immybot-cli maintenance-tasks create-global-by-id - Create global by id
immybot-cli maintenance-tasks create-global-by-id-param-block-from-parameters - Create global by id param block from parameters
immybot-cli maintenance-tasks create-local - Create local
immybot-cli maintenance-tasks create-local-by-id - Create local by id
immybot-cli maintenance-tasks create-local-by-id-migrate-local-to-global - Create local by id migrate local to global
immybot-cli maintenance-tasks create-local-by-id-param-block-from-parameters - Create local by id param block from parameters
immybot-cli maintenance-tasks create-validate-param-block-parameters - Create validate param block parameters
immybot-cli maintenance-tasks delete-global-by-id - Delete global by id
immybot-cli maintenance-tasks delete-local-by-id - Delete local by id
immybot-cli maintenance-tasks get-global - Get global
immybot-cli maintenance-tasks get-global-by-id - Get global by id
immybot-cli maintenance-tasks get-local - Get local
immybot-cli maintenance-tasks get-local-by-id - Get local by id
immybot-cli maintenance-tasks get-local-by-id-migrate-local-to-global-what-if - Get local by id migrate local to global what if
immybot-cli maintenance-tasks get-reference-count - Get reference count
immybot-cli maintenance-tasks get-search - Get search

me - Manage me

immybot-cli me - Gets all role assignments and groups for the current user

media - Manage media

immybot-cli media create-global-by-id - Create global by id
immybot-cli media create-global-upload - Create global upload
immybot-cli media create-local-by-id - Create local by id
immybot-cli media create-local-by-id-authorization - Create local by id authorization
immybot-cli media create-local-upload - Create local upload
immybot-cli media create-request-file-download-url - Create request file download url
immybot-cli media create-support-upload - Create support upload
immybot-cli media delete-global-by-id - Delete global by id
immybot-cli media delete-local-by-id - Delete local by id
immybot-cli media get-global - Get global
immybot-cli media get-global-by-id - Get global by id
immybot-cli media get-global-by-id-download-url - Get global by id download url
immybot-cli media get-local - Get local
immybot-cli media get-local-by-id - Get local by id
immybot-cli media get-local-by-id-authorization - Get local by id authorization
immybot-cli media get-local-by-id-download-url - Get local by id download url
immybot-cli media get-search - Get search

metrics - Manage metrics

immybot-cli metrics create-circuit-breakers-isolate - Create circuit breakers isolate
immybot-cli metrics create-circuit-breakers-reset - Create circuit breakers reset
immybot-cli metrics get-circuit-breakers - Get circuit breakers
immybot-cli metrics get-provider-links - Get provider links
immybot-cli metrics get-provider-links-by-provider-link-id-rate-limit-statistics - Returns the current rate limiter statistics for a provider link. 200: stats available. 204: provider not initialized.

notifications - Manage notifications

immybot-cli notifications create-acknowledge - Create acknowledge
immybot-cli notifications get-dx - Get dx
immybot-cli notifications get-unacknowledged - Get unacknowledged
immybot-cli notifications list - List

oauth - Manage oauth

immybot-cli oauth create-access-tokens-by-id-refresh - Create access tokens by id refresh
immybot-cli oauth create-begin-auth-code-flow - Create begin auth code flow
immybot-cli oauth create-fail-auth-code-flow - Create fail auth code flow
immybot-cli oauth create-finish-auth-code-flow - Create finish auth code flow
immybot-cli oauth delete-access-tokens-by-id - Delete access tokens by id
immybot-cli oauth get-access-tokens - Get access tokens
immybot-cli oauth get-access-tokens-by-id-by-access-token-id - Get access tokens by id by access token id

persons - Manage persons

immybot-cli persons create - Create
immybot-cli persons create-add-tags - Create add tags
immybot-cli persons create-remove-tags - Create remove tags
immybot-cli persons delete-by-id - Delete by id
immybot-cli persons get-by-id - Get by id
immybot-cli persons get-dx - Get dx
immybot-cli persons get-requesting-access - Get requesting access
immybot-cli persons list - List
immybot-cli persons update-by-id - Update by id

plugins - Manage plugins

immybot-cli plugins create-api-v1-by-provider-link-id-by-catch-all - Create api v1 by provider link id by catch all
immybot-cli plugins get-api-v1-by-provider-link-id-by-catch-all - Get api v1 by provider link id by catch all
immybot-cli plugins get-api-v1-by-provider-link-id-by-catch-all-v2 - Get api v1 by provider link id by catch all v2

preferences - Manage preferences

immybot-cli preferences get-tenants-by-tenant-id - Get tenants by tenant id
immybot-cli preferences list - List
immybot-cli preferences update-application - Update application
immybot-cli preferences update-my - Update my
immybot-cli preferences update-tenants-by-tenant-id - Update tenants by tenant id

provider-agents - Manage provider agents

immybot-cli provider-agents create-bulk-delete-pending - Create bulk delete pending
immybot-cli provider-agents create-identify - Identify agents that are marked with requiring manual identification
immybot-cli provider-agents create-resolve-failure-by-failure-id - Create resolve failure by failure id
immybot-cli provider-agents create-resolve-failures - Create resolve failures
immybot-cli provider-agents get-pending - Get pending
immybot-cli provider-agents get-pending-counts - Get pending counts

provider-links - Manage provider links

immybot-cli provider-links create - Create
immybot-cli provider-links create-create-with-external-provider-reference - Create create with external provider reference
immybot-cli provider-links create-verify-with-external-provider-reference - Create verify with external provider reference
immybot-cli provider-links delete-by-id - Delete by id
immybot-cli provider-links get-by-id - Get by id
immybot-cli provider-links list - List
immybot-cli provider-links update-by-id - Update by id

provider-types - Manage provider types

immybot-cli provider-types get-client-group-types-by-client-group-type-id-client-groups - Get client group types by client group type id client groups
immybot-cli provider-types get-device-group-types-by-device-group-type-id-device-groups - Get device group types by device group type id device groups
immybot-cli provider-types get-form-dropdown-options-by-key - Get form dropdown options by key
immybot-cli provider-types list - List

rmm-links - Manage rmm links

immybot-cli rmm-links create - Create
immybot-cli rmm-links get-by-id - Get by id
immybot-cli rmm-links list - List
immybot-cli rmm-links update-by-id - Update by id

roles - Manage roles

immybot-cli roles create - Create
immybot-cli roles delete-by-id - Delete by id
immybot-cli roles get-by-id - Get by id
immybot-cli roles get-permissions - Get permissions
immybot-cli roles list - List
immybot-cli roles update-by-id - Update by id

run-immy-service - Manage run immy service

immybot-cli run-immy-service - Create

run-immy-service-new - Manage run immy service new

immybot-cli run-immy-service-new - Create

schedules - Manage schedules

immybot-cli schedules create - Create
immybot-cli schedules create-bulk-cancel - Create bulk cancel
immybot-cli schedules create-bulk-delete - Create bulk delete
immybot-cli schedules create-bulk-run-now - Create bulk run now
immybot-cli schedules delete-by-id - Delete by id
immybot-cli schedules get-by-id - Get by id
immybot-cli schedules get-running-ids - Get running ids
immybot-cli schedules list - List
immybot-cli schedules update-bulk-update-status - Update bulk update status
immybot-cli schedules update-by-id - Update by id

scripts - Manage scripts

immybot-cli scripts create-debug-cancel-by-cancellation-id - Create debug cancel by cancellation id
immybot-cli scripts create-default-variables - Create default variables
immybot-cli scripts create-does-have-param-block - Create does have param block
immybot-cli scripts create-duplicate - Create duplicate
immybot-cli scripts create-functions-syntax - Execute a cloud script that returns the syntax for a specific command
immybot-cli scripts create-global - Create global
immybot-cli scripts create-global-by-id - Create global by id
immybot-cli scripts create-language-service-start - Create language service start
immybot-cli scripts create-local - Create local
immybot-cli scripts create-local-by-id - Create local by id
immybot-cli scripts create-local-by-id-authorization - Create local by id authorization
immybot-cli scripts create-local-by-id-migrate-local-to-global - Create local by id migrate local to global
immybot-cli scripts create-run - Create run
immybot-cli scripts create-run-adhoc-metascript - Create run adhoc metascript
immybot-cli scripts create-set-preflight-enablement - Create set preflight enablement
immybot-cli scripts create-syntax-check - Create syntax check
immybot-cli scripts create-validate-param-block-parameters - Create validate param block parameters
immybot-cli scripts delete-global-by-id - Delete global by id
immybot-cli scripts delete-local-by-id - Delete local by id
immybot-cli scripts get-disabled-preflight - Get disabled preflight
immybot-cli scripts get-dx - Get dx
immybot-cli scripts get-functions - Execute a cloud script that returns results of Get-Command
immybot-cli scripts get-global - Get global
immybot-cli scripts get-global-by-id - Get global by id
immybot-cli scripts get-global-by-id-audit - Get global by id audit
immybot-cli scripts get-global-by-id-references - Get global by id references
immybot-cli scripts get-global-names - Get global names
immybot-cli scripts get-language-service-by-terminal-id-language - Get language service by terminal id language
immybot-cli scripts get-local - Get local
immybot-cli scripts get-local-by-id - Get local by id
immybot-cli scripts get-local-by-id-audit - Get local by id audit
immybot-cli scripts get-local-by-id-authorization - Get local by id authorization
immybot-cli scripts get-local-by-id-migrate-local-to-global-what-if - Get local by id migrate local to global what if
immybot-cli scripts get-local-by-id-references - Get local by id references
immybot-cli scripts get-local-names - Get local names
immybot-cli scripts get-references-count - Get references count
immybot-cli scripts get-search - Get search

smtp-configs - Manage smtp configs

immybot-cli smtp-configs create - Create
immybot-cli smtp-configs create-by-tenant-id - Create by tenant id
immybot-cli smtp-configs create-send-test-email - Create send test email
immybot-cli smtp-configs delete-by-tenant-id - Delete by tenant id
immybot-cli smtp-configs get-by-tenant-id - Get by tenant id
immybot-cli smtp-configs list - List

software - Manage software

immybot-cli software create-global - Create global
immybot-cli software create-global-analyze - Create global analyze
immybot-cli software create-global-by-identifier-versions - Create global by identifier versions
immybot-cli software create-global-fast-create - Create global fast create
immybot-cli software create-global-upload - Create global upload
immybot-cli software create-local - Create local
immybot-cli software create-local-analyze - Create local analyze
immybot-cli software create-local-by-identifier-authorization - Create local by identifier authorization
immybot-cli software create-local-by-identifier-migrate-local-to-global - Create local by identifier migrate local to global
immybot-cli software create-local-by-identifier-versions - Create local by identifier versions
immybot-cli software create-local-fast-create - Create local fast create
immybot-cli software create-local-upload - Create local upload
immybot-cli software delete-global-by-identifier - Delete global by identifier
immybot-cli software delete-global-by-identifier-versions-by-semantic-version - Delete global by identifier versions by semantic version
immybot-cli software delete-local-by-identifier - Delete local by identifier
immybot-cli software delete-local-by-identifier-versions-by-semantic-version - Delete local by identifier versions by semantic version
immybot-cli software get-global - Get global
immybot-cli software get-global-by-identifier - Get global by identifier
immybot-cli software get-global-by-identifier-latest - Get global by identifier latest
immybot-cli software get-global-by-identifier-versions - Get global by identifier versions
immybot-cli software get-global-by-identifier-versions-by-semantic-version - Get global by identifier versions by semantic version
immybot-cli software get-global-by-identifier-versions-by-semantic-version-request-download - Get global by identifier versions by semantic version request download
immybot-cli software get-local - Get local
immybot-cli software get-local-by-identifier - Get local by identifier
immybot-cli software get-local-by-identifier-authorization - Get local by identifier authorization
immybot-cli software get-local-by-identifier-latest - Get local by identifier latest
immybot-cli software get-local-by-identifier-migrate-local-to-global-what-if - Get local by identifier migrate local to global what if
immybot-cli software get-local-by-identifier-versions - Get local by identifier versions
immybot-cli software get-local-by-identifier-versions-by-semantic-version - Get local by identifier versions by semantic version
immybot-cli software get-local-by-identifier-versions-by-semantic-version-request-download - Get local by identifier versions by semantic version request download
immybot-cli software update-global-by-identifier - Update global by identifier
immybot-cli software update-global-by-identifier-versions-by-semantic-version - Update global by identifier versions by semantic version
immybot-cli software update-local-by-identifier - Update local by identifier
immybot-cli software update-local-by-identifier-versions-by-semantic-version - Update local by identifier versions by semantic version

syncs - Manage syncs

immybot-cli syncs create-azure-user - Create azure user
immybot-cli syncs create-expire-pending-sessions - Create expire pending sessions
immybot-cli syncs create-trigger-user-affinity - Create trigger user affinity

system - Manage system

immybot-cli system create-disable-immy-support-access - Create disable immy support access
immybot-cli system create-enable-immy-support-access - Create enable immy support access
immybot-cli system create-is-immy-support-access-granted - Create is immy support access granted
immybot-cli system create-pull-update - Create pull update
immybot-cli system create-request-form-support - Create request form support
immybot-cli system create-request-session-support - Create request session support
immybot-cli system create-restart-backend - Create restart backend
immybot-cli system create-update-release-channel - Create update release channel
immybot-cli system get-immy-support-access-grant-details - Get immy support access grant details
immybot-cli system get-releases - Get releases
immybot-cli system get-timezones - Get timezones

tags - Manage tags

immybot-cli tags create - Create
immybot-cli tags create-by-id - Create by id
immybot-cli tags delete-by-id - Delete by id
immybot-cli tags get-by-id - Get by id
immybot-cli tags list - List

target-assignments - Manage target assignments

immybot-cli target-assignments create - Create
immybot-cli target-assignments create-change-request-by-change-request-id-v2 - Create change request by change request id v2
immybot-cli target-assignments create-change-request-v2 - Create change request v2
immybot-cli target-assignments create-duplicate - Create duplicate
immybot-cli target-assignments create-duplicates - Create duplicates
immybot-cli target-assignments create-global-by-id-notes - Create global by id notes
immybot-cli target-assignments create-global-by-id-override - Create global by id override
immybot-cli target-assignments create-global-create - Create global create
immybot-cli target-assignments create-migrate-deployments-to-provider-links - Create migrate deployments to provider links
immybot-cli target-assignments create-migrate-to-superseding-assignment - Create migrate to superseding assignment
immybot-cli target-assignments create-migrate-to-superseding-assignment-what-if - Create migrate to superseding assignment what if
immybot-cli target-assignments create-optional-approvals-by-id - Create optional approvals by id
immybot-cli target-assignments create-persons-target-preview - Create persons target preview
immybot-cli target-assignments create-recommended-approvals-update - Create recommended approvals update
immybot-cli target-assignments create-target-preview - Create target preview
immybot-cli target-assignments create-tenant-target-preview - Create tenant target preview
immybot-cli target-assignments create-update-maintenance-item-order - Create update maintenance item order
immybot-cli target-assignments create-visibility - Create visibility
immybot-cli target-assignments delete-by-id - Delete by id
immybot-cli target-assignments delete-global-by-id - Delete global by id
immybot-cli target-assignments get-by-id - Get by id
immybot-cli target-assignments get-change-request-by-change-request-id - Get change request by change request id
immybot-cli target-assignments get-change-request-by-change-request-id-diff - Get change request by change request id diff
immybot-cli target-assignments get-change-requests - Get change requests
immybot-cli target-assignments get-global - Get global
immybot-cli target-assignments get-global-by-id - Get global by id
immybot-cli target-assignments get-global-by-id-type - Get global by id type
immybot-cli target-assignments get-maintenance-item-orders - Get maintenance item orders
immybot-cli target-assignments get-optional-approvals-computer-by-computer-id - Get optional approvals computer by computer id
immybot-cli target-assignments get-recommended-approvals - Get recommended approvals
immybot-cli target-assignments list - List
immybot-cli target-assignments update-batch-update - Update batch update
immybot-cli target-assignments update-by-id - Update by id
immybot-cli target-assignments update-global-by-id - Update global by id

tenants - Manage tenants

immybot-cli tenants create - Create
immybot-cli tenants create-add-tags - Create add tags
immybot-cli tenants create-bulk-create - Create bulk create
immybot-cli tenants create-bulk-delete - Create bulk delete
immybot-cli tenants create-bulk-merge - Create bulk merge
immybot-cli tenants create-remove-parent - Create remove parent
immybot-cli tenants create-remove-tags - Create remove tags
immybot-cli tenants create-resolve-assignments-for-maintenance-item - Create resolve assignments for maintenance item
immybot-cli tenants create-set-parent - Create set parent
immybot-cli tenants create-update-azure-link - Create update azure link
immybot-cli tenants get-by-id - Get by id
immybot-cli tenants get-computer-counts - Get computer counts
immybot-cli tenants get-excluded-from-cross-deployments - Get excluded from cross deployments
immybot-cli tenants get-software-from-inventory-by-id - Get software from inventory by id
immybot-cli tenants get-software-from-inventory-dx - Get software from inventory dx
immybot-cli tenants get-software-from-inventory-export - Streams the contents of the detected computer software table as a CSV file to the client
immybot-cli tenants list - List
immybot-cli tenants update-activate-by-id - Update activate by id
immybot-cli tenants update-by-id - Update by id
immybot-cli tenants update-deactivate-by-id - Update deactivate by id

user-role-assignments - Manage user role assignments

immybot-cli user-role-assignments create-category-resource-create - Create category resource create
immybot-cli user-role-assignments create-msp-create - Create msp create
immybot-cli user-role-assignments create-owner-create - Create owner create
immybot-cli user-role-assignments create-specific-resource-create - Create specific resource create
immybot-cli user-role-assignments create-specific-tenant-create - Create specific tenant create
immybot-cli user-role-assignments create-tag-resource-create - Create tag resource create
immybot-cli user-role-assignments create-tenant-tag-create - Create tenant tag create
immybot-cli user-role-assignments create-user-tenant-create - Create user tenant create
immybot-cli user-role-assignments delete-delete - Delete delete
immybot-cli user-role-assignments get-users-by-user-id - Get users by user id
immybot-cli user-role-assignments get-users-by-user-id-count - Get users by user id count
immybot-cli user-role-assignments list - List

user_session - Manage user session

immybot-cli user-session get-login - Get login
immybot-cli user-session get-logout - Get logout
immybot-cli user-session get-me - Get me
immybot-cli user-session get-refresh - Get refresh

users - Manage users

immybot-cli users create-bulk-create - Create bulk create
immybot-cli users create-by-id - Create by id
immybot-cli users create-invalidate-cache - Create invalidate cache
immybot-cli users create-stop-impersonating - Create stop impersonating
immybot-cli users create-submit-feedback - Create submit feedback
immybot-cli users create-update-expiration - Create update expiration
immybot-cli users delete-bulk-delete - Delete bulk delete
immybot-cli users delete-by-id - Delete by id
immybot-cli users get-by-id - Get by id
immybot-cli users get-claims - Get claims
immybot-cli users list - List

webhooks - Manage webhooks

immybot-cli webhooks create-by-id - Create by id
immybot-cli webhooks get-by-id - Get by id

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

immybot-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match - fall back to --help or use a narrower query.

Recipes

Morning triage in one call

immybot-cli session-triage --since 24h --agent --select clusters.reason,clusters.action,clusters.computer_count

Returns only the distinct failure causes and how many machines each hit, which is the whole decision surface for opening tickets.

CVE sweep across every client

immybot-cli version-spread "Google Chrome" --min-version 140 --agent

Ranks installed versions with a real semver comparator and lists the tenants and machines still below the floor.

Explain a missed deployment

immybot-cli assignment-explain 4821 --agent

Shows every target assignment resolving onto that computer, which scope matched, and which rules were shadowed.

Check reach before editing a shared script

immybot-cli script-blast-radius 312 --agent

Walks the script to its consuming tasks and packages and out to the computers those assignments resolve onto.

Find silently stalled onboards

immybot-cli onboarding-stalled --older-than 3d --agent

Buckets the onboarding queue by age and shows whether an onboarding session was ever attempted and how it ended.

Auth Setup

ImmyBot authenticates through Microsoft Entra ID rather than an ImmyBot-issued key. Register an app in Entra ID, create a client secret, then in ImmyBot go to Show More > People > New and paste the Enterprise Application's object ID into the AD External ID field, promoting that person to an admin user. The CLI then needs four values: IMMYBOT_SUBDOMAIN (your instance name without .immy.bot), IMMYBOT_TENANT_ID, IMMYBOT_CLIENT_ID, and IMMYBOT_CLIENT_SECRET. The client-credentials token is minted against login.microsoftonline.com and cached automatically; the API scope is derived from your instance URL, and IMMYBOT_OAUTH_SCOPE overrides it if your tenant exposes a different App ID URI.

Run immybot-cli doctor to verify setup.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color.

Pipeable - JSON on stdout, errors on stderr
Filterable - --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
```
immybot-cli access list --agent --select addons,backendRegAppId,canManageCrossTenantDeployments
```
Previewable - --dry-run shows the request without sending
Offline-friendly - sync/search commands can use the local SQLite store when available
Non-interactive - never prompts, every input is a flag
Explicit confirmation - --agent does not imply --yes; pass --yes separately only after the target, arguments, and side effects are clear
Explicit retries - use --idempotent only when an already-existing create should count as success, and use --ignore-missing only when a missing delete target should count as success

Response envelope

Commands that read from the local store or the API wrap output in a provenance envelope:

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal AND no machine-format flag (--json, --csv, --compact, --quiet, --plain, --select) is set - piped/agent consumers and explicit-format runs get pure JSON on stdout.

Paths and state

Agents should treat the CLI's path resolver as part of the runtime contract:

Use --home <dir> for one invocation, or set IMMYBOT_HOME=<dir> to relocate all four path kinds under one root.
Use per-kind env vars only when a specific kind must diverge: IMMYBOT_CONFIG_DIR, IMMYBOT_DATA_DIR, IMMYBOT_STATE_DIR, IMMYBOT_CACHE_DIR.
Resolution order is per-kind env var, --home, IMMYBOT_HOME, XDG (XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME), then platform defaults.
config contains settings like config.toml and profiles. data contains credentials.toml, data.db, cookies, and auth sidecars. state contains persisted queries, jobs, and teach.log. cache contains regenerable HTTP/cache files.
Stored secrets live in credentials.toml under the data dir. Existing legacy config.toml secrets are read for compatibility and leave config.toml on the first auth write.
Run immybot-cli doctor --fail-on warn to surface path and credential-location warnings. agent-context exposes a schema v4 paths block for agents that need the resolved dirs.

For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags:

{
  "mcpServers": {
    "immybot": {
      "command": "immybot-mcp",
      "env": {
        "IMMYBOT_HOME": "/srv/immybot"
      }
    }
  }
}

Fleet precedence: an inherited per-kind env var overrides an explicit --home for that kind. Use IMMYBOT_HOME or per-kind vars as durable fleet levers, and use --home only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing IMMYBOT_HOME, or doctor will not find credentials left under the former root.

Automatic learning

This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a flag_alias candidate, and a teach on a query family without a playbook auto-synthesizes a playbook_candidate from the session's journal. Your job is judgment only: recall first, act on surfaced candidates, teach the final answer, playbook amend when you observe a correction. You never record failures by hand.

Step 1: `recall` before any discovery

Before list/search/drill commands on a new user question, run:

immybot-cli recall "<user's question>" --agent

The response envelope:

{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "immybot-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and learnings list and learnings candidates are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught.

Step 2: decision tree

Read candidates, playbook, notes, results[0], and warnings in that order:

if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `immybot-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

Playbook and Notes are orthogonal to the per-resource path. A recall response can carry both a Playbook AND a Results[] hit - use both: the Playbook tells you which choreography to run; the resource hits short-circuit specific steps. Default to skipping mismatches; pass --debug-mismatches only when investigating cold-start surprises.

Candidate judgment details: learnings confirm <id> prints the candidate's full payload before materializing it - check that the printed payload matches the behavior you verified. learnings reject <id> tombstones the derivation signature so the same candidate does not resurface. The envelope carries only the few candidates worth acting on now; immybot-cli learnings candidates lists the full open set.

Graceful degradation: if learnings confirm is an unknown command, you are driving an older binary - ignore the candidates guidance and follow the rest of the protocol.

Step 3: always read `warnings`

low_confidence: row exists at confidence<2. Treat as a hint, not a skip-discovery hit.
resource_not_in_store: the local store doesn't have the resource the learning points at. The match validator couldn't classify entities - direct-fetch and re-evaluate.
cross_alias_match (per-result): the row was taught under a different alias and matched the live query's canonical via entity_lookups (e.g., a "USA" teach satisfying a "United States" recall). Trust the resource_id.
similar_shape_different_entity:<canonical> (top-level): a structurally matching row exists but its canonical entity differs from the live query's. Treated as cold start; the warning carries the conflicting canonical as a hint, but the row is NOT promoted into Results.
ambiguous_alias (top-level): a single query entity resolved to multiple canonicals (e.g., "Cards" → Arizona Cardinals + St. Louis Cardinals). Surface the ambiguity from context before committing to a resource.
candidates_present (top-level): the envelope carries a candidates section. Handle it via the candidates branch in Step 2 before anything else.
lookup_refresh_available (top-level): an entity in the query has no lookup row yet, but synced data could provide one. Run immybot-cli sync to refresh entity lookups.
Top-level no_learnings_for_query_family: the table had no rows above the Jaccard floor. Pure cold start.

Step 4: `teach &` after finalizing your response - always

Teaching is unconditional. After resolving a query the store could not answer, background-teach the final resource mapping - no call-count threshold, no judging whether it was "worth" learning. The teach is the anchor of the loop: it triggers playbook synthesis for a family without a playbook, and same-referent phrasings fold into one family so near-duplicate teaches do not fragment the store. Fire it after assembling your user-facing response but BEFORE emitting it, with a shell & so the call returns immediately:

immybot-cli teach --query "<user's question>" --resource-type <type> --resource <id1> --resource <id2>
# (append shell `&` to background it)

Silent on success. Errors only land in teach.log under the resolved state dir. Teach the most specific resource - if the user asked a broad question and you walked through parent records to find the specific answer, teach the leaf id, not the parent. The CLI uses seeded entity_lookups for cross-alias resolution at recall time, so a teach under one alias (e.g., "Niners") satisfies future queries under another alias (e.g., "49ers", "San Francisco") automatically.

PII rule: teach the structural question with identifiers stripped - never include names, emails, phone numbers, account ids, or other personal identifiers in taught queries or notes. The CLI scans teach queries for obvious email/phone shapes and warns, but does not block; strip before teaching rather than relying on the warning.

Step 5: playbooks - optional flags, automatic synthesis

You do not need to decide whether a session "deserves" a playbook: a teach on a family without one auto-synthesizes a playbook_candidate from the session's journal, and the next session judges it via confirm/reject. Attach explicit playbook flags only when you already hold choreography worth recording verbatim - workarounds the CLI didn't surface (silently-dropped flags, undocumented params, pagination tricks, payload gotchas). Prefer the integrated one-call form - record the resource learning and the playbook in the same teach invocation:

# Common case: record both the resource learning AND the playbook in one call.
immybot-cli teach \
  --query "<user's question>" \
  --resource <id> \
  --playbook-file ~/playbooks/<shape>.json \
  --playbook-notes-file ~/playbooks/<shape>-notes.md
# (append shell `&` to background it)

# Alternate: playbook-only (no resource to record alongside).
immybot-cli teach-playbook \
  --query "<user's question>" \
  --playbook-file ~/playbooks/<shape>.json \
  --notes-file ~/playbooks/<shape>-notes.md

Playbook files are JSON with steps, entity_slots, expected_tool_calls. Notes files are markdown carrying the gotchas verbatim. File-free callers (MCP-only agents) pass the same content inline: --playbook-json and --playbook-notes on the integrated teach form, --playbook-json and --notes on teach-playbook. On the integrated teach form, the playbook flags are optional - omit them entirely for a resource-only teach. On the standalone teach-playbook form, at least one of the playbook and notes flags must be set; both empty is rejected. Playbooks are keyed on the structural query family (entities stripped) so a recipe taught from one entity-shaped query applies to every other query of the same shape, with slots_resolved binding the live query's canonical at recall time.

When you DO find a playbook on a future recall, treat it as ground truth: replay the steps with slots_resolved substitutions, skip the discovery that the choreography already documents, and read notes before any step.

Step 6: `playbook amend &` when your debug response identifies a correction

If your debug-protocol response identifies a concrete correction the notes or playbook should know - a workaround, an undocumented endpoint shape, a stale field name, observed schema drift, an empty-payload fallback - fire playbook amend BEFORE emitting your user-facing response. Same fire-and-forget posture as teach.

immybot-cli playbook amend \
  --query "<exact recall query string>" \
  --add-note "<your concrete correction>"
# (append shell `&` to background it)

What counts as worth amending: a behavior you OBSERVED this session that future-you would benefit from knowing. Examples worth amending:

A workaround for a CLI surface that silently drops or misorders a flag.
An undocumented endpoint shape (response wrapped in {meta, results}, payload nested two levels deeper than the docs claim).
Observed schema drift (a field renamed, an index that shifted between seasons, a category label that the API now returns lower-cased).

What does NOT belong in notes:

The year-specific or entity-specific answer to the user's question. That's the response, not a learning.
Per-team / per-athlete / per-row data the playbook already retrieves at runtime.
Statements that paraphrase what the existing notes already say.

The amend command appends to the family's existing notes with a timestamped marker ([amend YYYY-MM-DDTHH:MMZ]: <text>). Multiple amends accumulate; the audit trail is visible. If no playbook exists yet for the family, amend creates a notes-only one (so cold-start corrections still land).

PII discipline for amend notes

playbook amend notes are designed to potentially flow upstream as shared knowledge in future versions of the Printing Press. Keep them clean of user-identifying content so the upstream-contribution path stays open without retroactive scrubbing:

Do NOT embed paths to user filesystems, personal API keys or tokens, user email addresses, user GitHub handles, or specific query histories tied to a single user.
Acceptable: endpoint shapes, undocumented field names, API gotchas, observed schema drift, workarounds for CLI surfaces, generalizable pagination or retry tactics.

If a correction is only meaningful with user-specific context, it belongs in a personal note, not in the playbook amend.

Measuring the loop

immybot-cli learnings stats reports recall hit rate, teach-to-reuse, playbook resolution rate, and candidate confirm/reject counts from the local learn_events table. Rates are null until they have a denominator; everything stays on this machine. Use it to check whether the loop is earning its keep for this CLI.

Disabling learning

--no-learn on a single command short-circuits both recall and the teach write path. Use for deterministic agent flows or tests that must not be affected by accumulated learnings.
IMMYBOT_NO_LEARN=true in the environment globally disables the pipeline.

Agent Feedback

When you (or the agent) notice something off about this CLI, record it:

immybot-cli feedback "the --since flag is inclusive but docs say exclusive"
immybot-cli feedback --stdin < notes.txt
immybot-cli feedback list --json --limit 10

Entries are stored locally as feedback.jsonl under the resolved data dir. They are never POSTed unless IMMYBOT_FEEDBACK_ENDPOINT is set AND either --send is passed or IMMYBOT_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

Output Delivery

Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Sink	Effect
`stdout`	Default; write to stdout only
`file:<path>`	Atomically write output to `<path>` (tmp + rename)
`webhook:<url>`	POST the output body to the URL (`application/json` or `application/x-ndjson` when `--compact`)

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

Named Profiles

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled or recurring agent reuses the same saved flags while providing different input each run.

immybot-cli profile save briefing --json
immybot-cli --profile briefing access list
immybot-cli profile list --json
immybot-cli profile show briefing
immybot-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.

Async Jobs

For endpoints that submit long-running work, the generator detects the submit-then-poll pattern (a job_id/task_id/operation_id field in the response plus a sibling status endpoint) and wires up three extra flags on the submitting command:

Flag	Purpose
`--wait`	Block until the job reaches a terminal status instead of returning the job ID immediately
`--wait-timeout`	Maximum wait duration (default 10m, 0 means no timeout)
`--wait-interval`	Initial poll interval (default 2s; grows with exponential backoff up to 30s)

Use async submission without --wait when you want to fire-and-forget; use --wait when you want one command to return the finished artifact.

Exit Codes

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Resource not found
4	Authentication required
5	API error (upstream issue)
7	Rate limited (wait and retry)
10	Config error

Argument Parsing

Parse $ARGUMENTS:

Empty, help, or --help → show immybot-cli --help output
Starts with install → ends with mcp → MCP installation; otherwise → see Prerequisites above
Anything else → Direct Use (execute as CLI command with --agent)

MCP Server Installation

Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:

claude mcp add immybot-mcp -- immybot-mcp

Verify: claude mcp list

Direct Use

Check if installed: which immybot-cli If not found, offer to install (see Prerequisites at the top of this skill).
Match the user query to the best command from the Unique Capabilities and Command Reference above.

Execute with the --agent flag:

immybot-cli <command> [subcommand] [args] --agent

If ambiguous, drill into subcommand help: immybot-cli <command> --help.