# AI tools and documentation
Source: https://docs.usepointed.ai/docs/ai-tools

Give your assistant access to Pointed CLI documentation and understand which tools can change workspace data.

## Read the documentation with an assistant

The public documentation has a [page index](https://docs.usepointed.ai/llms.txt) and [complete text](https://docs.usepointed.ai/llms-full.txt) for tools that read Markdown.

Mintlify also hosts a documentation MCP server:

```text theme={null}
https://docs.usepointed.ai/mcp
```

Use that URL in an MCP client that supports remote HTTP servers. It does not require your Pointed credentials.

The documentation server searches and reads the published CLI guides. It also offers a tool for submitting documentation feedback. It has no access to your private Pointed workspace, customer contacts, interviews, or response exports, and cannot send invitations or change records.

## Use the CLI from an agent

An agent with terminal access can use the installed CLI after you complete [authentication](/docs/authentication). Start with `pointed auth whoami`, `pointed --help`, and read commands such as `pointed accounts list` to confirm the intended account and operation.

Review customer records and recipient selections before a write. Creating contacts or campaigns, enrolling accounts, and generating links change workspace data. Sending or reminding an invitation contacts a customer and should follow your explicit approval.

For batch operations, inspect the JSON output and exit status. A nonzero exit can include successful items alongside failures; [response export manifests](/docs/response-exports) preserve each outcome. Check what succeeded before retrying.

## Pointed in ChatGPT

Adding this documentation MCP server to an assistant provides documentation lookup only. It does not install a Pointed app that operates your workspace in ChatGPT. Use the [CLI command reference](/docs/commands) for the operations available through the CLI, or [contact Pointed](https://usepointed.ai/contact?reason=general) about integration availability.


# Authentication
Source: https://docs.usepointed.ai/docs/authentication

Connect an existing Pointed account with browser login, or use an existing API key for automation.

## Browser login

Use browser login for interactive usage. First confirm you can [sign in to Pointed](https://app.usepointed.ai/sign-in) and access your workspace. If you are new to Pointed, [request access](https://usepointed.ai/contact?reason=general); joining a waitlist alone does not provide workspace access.

```bash theme={null}
pointed auth login
```

1. Leave the command running while the browser opens.
2. Sign in with your Pointed account and complete the authorization prompt.
3. Return to the terminal and wait for `Logged in successfully.`
4. Run `pointed auth whoami` to verify the authenticated account before creating or changing records.

The browser must run on the same computer as the CLI. Login uses a temporary callback at `http://127.0.0.1:3100/callback`. If the browser does not open, copy the URL printed by the CLI into your browser. A remote SSH session or container needs a compatible local callback setup; use an existing API key for unattended automation.

The CLI stores OAuth access and refresh tokens in a private local file:

```text theme={null}
~/.pointed/credentials.json
```

## API key

Use this option only if you already have a Pointed-compatible Clerk API key authorized for your workspace. If you need one, [contact Pointed](https://usepointed.ai/contact?reason=general) to confirm availability and provisioning. The CLI has no command to issue API keys.

Store the key in your shell's secret management or your automation provider's secret store, then expose it as `POINTED_API_KEY`:

```bash theme={null}
export POINTED_API_KEY="<your-existing-api-key>"
pointed auth whoami
```

The CLI checks `POINTED_API_KEY` before stored OAuth credentials. Do not put keys in source files, screenshots, public issues, or chat messages. To switch back to browser credentials, run `unset POINTED_API_KEY` in that shell and verify with `pointed auth whoami`.

## Refresh or sign out

If an OAuth token expires, refresh it and check your account again:

```bash theme={null}
pointed auth refresh
pointed auth whoami
```

If refresh fails, run `pointed auth login` again.

```bash theme={null}
pointed auth logout
```

Logout removes the locally stored OAuth credentials. It does not revoke an API key or unset `POINTED_API_KEY`. Remove the variable from your environment and secret store when you stop using it; contact Pointed if you need help revoking a key.

## Configuration

Local config is stored in:

```text theme={null}
~/.pointed/config.json
```

Inspect or update configuration:

```bash theme={null}
pointed config list
pointed config get apiBaseUrl
pointed config set apiBaseUrl https://app.usepointed.ai
```

The default API is `https://app.usepointed.ai`. Change the API or OAuth settings only when you are intentionally using another Pointed environment.

Useful environment overrides:

* `POINTED_API_URL`: override the API base URL
* `POINTED_OUTPUT_FORMAT`: set `json` or `table`
* `CLERK_FRONTEND_API_URL`: override hosted OAuth discovery
* `CLERK_OAUTH_CLIENT_ID`: override the OAuth client ID for development

For browser callback, expired-token, or permission problems, see [Troubleshooting](/docs/troubleshooting). Pointed's [privacy policy](https://usepointed.ai/privacy) explains how the service handles data.


# Changelog
Source: https://docs.usepointed.ai/docs/changelog

Published Pointed CLI releases and the source changes included in them.

## 0.2.0 — October 4, 2026

The first public npm release of [`@pointed/cli`](https://www.npmjs.com/package/@pointed/cli), including the earlier feature work and the October security and reliability fixes.

### Customer collection workflows

* Accounts, contacts, campaigns, survey links, and story template enrollment
* Account and campaign updates
* Invitation preview, test, send, reminder, and delivery issue clearing
* Smart intake preview and commit for account and contact imports
* Response data, transcript, media, summary, and manifest exports
* Browser OAuth login, refresh, logout, and existing API key support

### October fixes

* Private local credential/configuration files and export directories, with ownership and permission checks
* OAuth callback validation and terminal output escaping
* Opaque identifier handling and rejection of explicitly empty contact selectors
* Strict numeric validation and removal of unsupported contact department fields
* Complete batch results and failure exit status for partial operations
* Bounded campaign export pagination and manifests that report final download outcomes

Source changes: [local storage and OAuth hardening](https://github.com/PointedAI/usepointed-cli/pull/3) and [request targeting and operation reporting](https://github.com/PointedAI/usepointed-cli/pull/4).

## Development history before npm publication

### May 23, 2026

The source version moved to 0.2.0 with account/campaign updates, smart intake, and inline spinner feedback. These changes were published to npm as part of the October 4 release.

### April 26, 2026

Initial 0.1.0 source preparation included the core collection commands, story templates, invitation email, response exports, and authentication. Version 0.1.0 was not published to the public npm registry.


# Commands
Source: https://docs.usepointed.ai/docs/commands

Core Pointed CLI commands for accounts, contacts, campaigns, links, and invites.

## Accounts

```bash theme={null}
pointed accounts list
pointed accounts get <accountId>
pointed accounts create --name "Acme Corp" --industry "Technology"
pointed accounts update <accountId> --name "Acme Inc" --contract-value 120000
```

Contract values must be finite, nonnegative numbers without currency symbols or thousands separators. For example, use `120000`, not `120,000`.

## Contacts

```bash theme={null}
pointed contacts list --account-id <accountId>
pointed contacts create --account-id <accountId> --name "Jane Doe" --email jane@example.com
pointed contacts update <contactId> --email jane.new@example.com
pointed contacts delete <contactId>
```

Batch create contacts from JSON:

```bash theme={null}
pointed contacts create-batch --account-id <accountId> --input-file contacts.json
```

`contacts.json`:

```json theme={null}
[
  {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "title": "VP Product"
  }
]
```

Batch creation prints the complete result as JSON and exits with status 1 if any row fails. Existing contacts are reported separately and do not count as failed rows. Contact department fields are not supported; use `--title` for a job title.

## Campaigns

```bash theme={null}
pointed campaigns list --account-id <accountId>
pointed campaigns get <campaignId>
pointed campaigns create \
  --account-id <accountId> \
  --name "Renewal proof" \
  --context "Customer story collection for renewal" \
  --initial-question "What outcome did this work unlock?"
pointed campaigns update <campaignId> --name "Updated title" --max-rounds 5
```

`--max-rounds` requires a positive integer for campaigns and story templates.

## Links

```bash theme={null}
pointed links generate --campaign-id <campaignId>
pointed links generate --campaign-id <campaignId> --contact-ids id1,id2
pointed links generate --campaign-id <campaignId> --contact-emails jane@example.com,john@example.com
```

Omitting both contact selectors includes all account contacts. An explicitly empty selector is rejected, including an empty shell variable. Link generation prints all results and exits with status 1 if any selected contact fails.

## Invite email

```bash theme={null}
pointed invites email preview <inviteId>
pointed invites email send-test <inviteId> --email you@example.com
pointed invites email send <inviteId>
pointed invites email remind <inviteId>
pointed invites delivery-issue clear <inviteId>
```

## Smart intake

See [Smart intake](/docs/smart-intake) for the full workflow.

```bash theme={null}
pointed smart-intake preview --raw-input "Acme Corp, Jane Doe, jane@acme.com"
pointed smart-intake commit --session-id <sessionId> --resolutions '[{"rowIndex":0,"action":"commit"}]'
```


# Installation
Source: https://docs.usepointed.ai/docs/installation

Install Pointed CLI from npm or run it from source.

## Install from npm

The public npm package is [`@pointed/cli`](https://www.npmjs.com/package/@pointed/cli).

```bash theme={null}
npm install -g @pointed/cli
pointed --help
```

Update an existing installation with the same `npm install -g @pointed/cli` command.

## Requirements

* macOS or Linux with a filesystem that supports POSIX ownership and permissions
* Node.js 20 or newer; use Node.js 22 when developing or validating this repository
* An existing Pointed account with workspace access; [request access](https://usepointed.ai/contact?reason=general) if you do not have one
* A browser on the same computer for `pointed auth login`, or an existing Pointed-compatible API key for automation

Native Windows is not currently supported. The CLI checks local file ownership and permissions before using credentials, configuration, and export directories; Windows ACL validation is not implemented.

Installing the package does not grant workspace access or create an API key. Continue with [Authentication](/docs/authentication) after installation.

## Run from source

```bash theme={null}
git clone https://github.com/PointedAI/usepointed-cli.git
cd usepointed-cli
npm ci
npm run build
npm link
pointed --help
```

You can also run the built file directly:

```bash theme={null}
node dist/index.js --help
```

## Local files

The CLI stores configuration and OAuth credentials in `~/.pointed`. It requires that directory to be owned by your user with mode `0700`, and its JSON files to be regular, owner-only files with mode `0600`. It refuses unsafe permissions, symbolic links, and hard links.

Response exports use private directories and files too. See [Troubleshooting](/docs/troubleshooting#local-file-permission-errors) for recovery guidance.


# Quickstart
Source: https://docs.usepointed.ai/docs/quickstart

Sign in to your Pointed workspace, prepare customer interview links, and collect evidence from your terminal.

Pointed helps B2B teams collect customer evidence. Use the CLI to manage accounts and contacts, prepare interview campaigns, and export responses for analysis.

## Before you start

You need an existing Pointed account with access to your workspace, macOS or Linux, and Node.js 20 or newer. Node.js 22 is recommended for development.

<Note>
  Installing the CLI does not create a Pointed account. New users can [request access](https://usepointed.ai/contact?reason=general). If the Pointed site directs you to the waitlist, wait for access before continuing. Existing users can [sign in to Pointed](https://app.usepointed.ai/sign-in).
</Note>

## Install

```bash theme={null}
npm install -g @pointed/cli
pointed --version
```

## Log in

```bash theme={null}
pointed auth login
```

Complete sign-in in the browser on the same computer, then return to your terminal and verify your account:

```bash theme={null}
pointed auth whoami
pointed accounts list
```

The CLI uses `https://app.usepointed.ai` by default. See [Authentication](/docs/authentication) if sign-in fails or you need automation credentials.

## Create an account and contact

Here, an account is a customer organization in your Pointed workspace. It is separate from your Pointed sign-in. The following commands create records. You can reuse an existing customer account from `pointed accounts list`.

Replace placeholders such as `<accountId>` with the IDs returned by your commands, without the angle brackets. Use contact details you are authorized to add.

```bash theme={null}
pointed accounts create --name "Acme Corp" --industry "Technology"

pointed contacts create \
  --account-id <accountId> \
  --name "Jane Doe" \
  --email jane@example.com \
  --title "VP Product"
```

## Create a campaign

```bash theme={null}
pointed campaigns create \
  --account-id <accountId> \
  --name "Renewal proof" \
  --context "Customer story collection for renewal" \
  --initial-question "What outcome did this work unlock?"
```

## Generate links

```bash theme={null}
pointed links generate --campaign-id <campaignId> --contact-ids <contactId>
```

This prepares a link for the selected contact. Omitting both contact selectors includes every contact on the campaign account. Preparing links does not send invitation email.

## Review and share

Review the generated link before sharing it. To use Pointed invitation email, first [preview the invitation](/docs/commands#invite-email), then send it when you are ready. Sending and reminding are separate commands that contact the customer.

After a customer responds, [list and export responses](/docs/response-exports). For repeatable collection across accounts, use [story templates](/docs/story-templates).


# Response exports
Source: https://docs.usepointed.ai/docs/response-exports

Download response data, transcripts, media, summaries, and manifests.

## List responses

```bash theme={null}
pointed responses list --campaign-id <campaignId>
```

## Download one response

```bash theme={null}
pointed responses download \
  --campaign-id <campaignId> \
  --response-id <responseId> \
  --output-dir ./pointed-export
```

## Download all responses for a campaign

```bash theme={null}
pointed responses download \
  --campaign-id <campaignId> \
  --output-dir ./pointed-export
```

## Export shape

Single response:

```text theme={null}
<output-dir>/response-<contact-slug>-<date>-<response-id>-<unique-suffix>/
  response.json
  round-1-transcript.txt
  round-2-transcript.txt
  response-<contact-slug>-<date>-round-1.mp4
  response-<contact-slug>-<date>-round-2.mp4
  ai-summary.txt
  insights.json
  manifest.json
```

Full campaign:

```text theme={null}
<output-dir>/campaign-<title-slug>-<unique-suffix>/
  campaign.json
  manifest.json
  response-<contact-slug>-<date>-<response-id>-<unique-suffix>/
    response.json
    round-*-transcript.txt
    response-<contact-slug>-<date>-round-*.mp4
    ai-summary.txt
    insights.json
    manifest.json
```

Every run creates a new private export directory and preserves previous exports.

Each response's `manifest.json` includes final `processingWarnings` and a `videoDownloads` entry for each asset, with its filename, download status, and any failure reason. These reflect the download attempt, including network and file errors, rather than only the API's initial processing state.

Campaign exports also write a top-level `manifest.json`. It records every requested response as `exported`, `partial`, or `failed`, with its output directory when available and any warnings. `exportedResponses` counts fully exported responses; `failedResponses` includes partial exports.

The command exits with status 1 when a response cannot be exported or a ready video fails to download. Successfully written files are preserved, and campaign downloads continue attempting the remaining responses. Media that is still preparing or unavailable is recorded as a warning and does not alone make the command fail.


# Smart intake
Source: https://docs.usepointed.ai/docs/smart-intake

Bulk-import accounts and contacts with AI-powered parsing.

Smart intake uses an LLM to parse free-form text (CSV rows, pasted lists, copied tables) into structured account and contact records. The workflow has two steps: **preview** then **commit**.

## Preview

Submit raw text and receive a parsed preview with one row per detected contact.

```bash theme={null}
pointed smart-intake preview \
  --raw-input "Acme Corp, Jane Doe, jane@acme.com
Globex Inc, John Smith, john@globex.io"
```

Optionally attach a story template so created accounts are auto-enrolled:

```bash theme={null}
pointed smart-intake preview \
  --raw-input "Acme Corp, Jane Doe, jane@acme.com" \
  --story-template-id <templateId>
```

The response includes a `sessionId` and a `rows` array. Each row shows the parsed account name, contact name, contact email, and a status indicating whether it will create new records or match existing ones.

## Commit

After reviewing the preview, commit the session. Supply a resolution for every row.

```bash theme={null}
pointed smart-intake commit \
  --session-id <sessionId> \
  --resolutions '[{"rowIndex":0,"action":"commit"},{"rowIndex":1,"action":"skip"}]'
```

Or pass resolutions from a file:

```bash theme={null}
pointed smart-intake commit \
  --session-id <sessionId> \
  --input-file resolutions.json
```

### Resolution actions

| Action | Description |
| - | - |
| `commit` | Create the account and contact as parsed. |
| `skip` | Skip this row entirely. |
| `reroute` | Assign the contact to a different account. Requires `targetAccountId`. |
| `reuse_existing` | Link to the existing matched contact instead of creating a new one. |
| `route_to_personal_bucket` | Route the contact to a personal bucket account. |
| `allow_cross_account_duplicate` | Allow a contact that exists on another account. |

### Reroute example

```json theme={null}
[
  { "rowIndex": 0, "action": "commit" },
  { "rowIndex": 1, "action": "reroute", "targetAccountId": "<accountId>" }
]
```

## Idempotency

Each preview request requires an `idempotencyKey`. The CLI generates one automatically if you omit `--idempotency-key`. Reusing the same key returns the cached preview instead of re-running the LLM.


# Story templates
Source: https://docs.usepointed.ai/docs/story-templates

Use story templates to prepare account-level customer story collection.

Story templates are reusable collection plans. Enrolling an account prepares survey links for contacts on that account. It does not send customer email immediately.

## Create a template

```bash theme={null}
pointed story-templates create \
  --title "Renewal proof" \
  --customer-facing-name "ROI story" \
  --role "Economic buyer" \
  --goal "Capture ROI stories before renewal" \
  --initial-question "What changed after adopting the product?"
```

## Inspect templates

```bash theme={null}
pointed story-templates list
pointed story-templates get <templateId>
pointed story-templates enrollment-options <templateId>
```

## Enroll an account

```bash theme={null}
pointed story-templates enroll <templateId> \
  --account-id <accountId> \
  --auto-include-new-contacts
```

Enroll specific contacts:

```bash theme={null}
pointed story-templates enroll <templateId> \
  --account-id <accountId> \
  --contact-emails jane@example.com,john@example.com
```

Omitting both contact selectors includes all contacts on the account. Explicitly empty selectors, including empty shell variables, are rejected. Supply either `--contact-ids` or `--contact-emails`, not both.

## Manage enrollment

```bash theme={null}
pointed story-templates account <templateId> <accountId>
pointed story-templates set-auto-include <templateId> <accountId> --enabled false
```

`autoIncludeNewContacts` controls whether newly created contacts on the enrolled account should automatically receive prepared survey links for the template.

## Legacy imports

```bash theme={null}
pointed story-templates legacy-import-summary
pointed story-templates import-legacy
```

Legacy import creates story templates for eligible existing campaigns and attaches the existing campaign records. It does not send new customer email.


# Troubleshooting
Source: https://docs.usepointed.ai/docs/troubleshooting

Fix Pointed CLI setup issues and troubleshoot enabled ChatGPT or Codex connections.

## ChatGPT and Codex connections

These steps apply when a Pointed workspace integration has been enabled for you. The public [documentation MCP server](/docs/ai-tools) only searches these guides; it does not connect to your workspace.

* Connect through ChatGPT or Codex's OAuth connection flow. A hosted Pointed connection does not require installing the CLI or pasting an API key, token, password, or client secret into chat.
* Check the workspace reported by the connection. If access is denied or the workspace is wrong, open [Pointed](https://app.usepointed.ai/sign-in), confirm your account and selected workspace, then reconnect through the host.
* Interview evidence requires separate permission and may be disabled for a connection. Use the returned Pointed links to review results when access is unavailable.
* Saving a campaign draft does not send invitations, place calls, or start interviews. Review contacts, consent, and interview settings in Pointed before launching.
* If saving an account or draft times out, check Pointed before retrying. Ask the plugin to retry the same operation with the same request key; a new key can create a duplicate. The plugin manages that key for you.

For help, [contact Pointed](https://usepointed.ai/contact?reason=general) with the host you used, the workflow, and the safe error message. Do not include credentials, customer details, transcripts, or private workspace links.

## Check auth

Confirm you can sign in to [Pointed](https://app.usepointed.ai/sign-in) with the same account. If you only have waitlist access, [contact Pointed](https://usepointed.ai/contact?reason=general) before trying workspace commands.

```bash theme={null}
pointed auth whoami
```

If you are not authenticated:

```bash theme={null}
pointed auth login
```

For automation, use an existing authorized API key as described in [Authentication](/docs/authentication#api-key). To check whether your shell is using a key without printing it:

```bash theme={null}
test -n "$POINTED_API_KEY" && echo "POINTED_API_KEY is set"
```

An API key overrides browser credentials. To return to browser login:

```bash theme={null}
unset POINTED_API_KEY
pointed auth login
pointed auth whoami
```

## Browser login does not finish

Keep the CLI running while you sign in. If the browser did not open, visit the URL printed in the terminal on the same computer. The callback uses `127.0.0.1:3100`; another process on port 3100 or a browser running on a different machine can prevent it from reaching the CLI.

If the login attempt times out, start `pointed auth login` again. If a stored token expires, try `pointed auth refresh`, then `pointed auth whoami`. Do not share the authorization URL or token values in a support request.

## Local file permission errors

Use macOS or Linux. Native Windows ACL validation is not implemented.

Inspect the affected path first. The CLI expects `~/.pointed` to be owned by your user with mode `0700`; its JSON files must be regular files owned by your user with mode `0600`. It rejects symlinks, hard links, and paths owned by another user. Avoid running the CLI with `sudo`.

Correct permissions only after confirming that the path is your own directory or regular file. Preserve existing configuration and exports; do not delete the directory as a generic fix. If ownership is wrong or a link is involved, ask your administrator or [Pointed support](https://usepointed.ai/contact?reason=general) for help. Export directories must also be owned by you and not writable by other users.

## A batch or export reports failure

Read the complete output before retrying. Contact batches and link generation can succeed for some items and still exit with status 1 when others fail. Response exports preserve successful files and write [manifests](/docs/response-exports) with final outcomes. Retry only what still needs attention.

## Check environment

```bash theme={null}
pointed config get apiBaseUrl
pointed config set apiBaseUrl https://app.usepointed.ai
```

If `POINTED_API_URL` is set, it overrides the saved config.

## Use request IDs

CLI API responses include `meta.requestId`. Include that request ID when reporting a failed command.

For help, use [Pointed support](https://usepointed.ai/contact?reason=general) or [CLI issues](https://github.com/PointedAI/usepointed-cli/issues). Include the CLI version, operating system, command name, error, and request ID when available. Remove tokens, customer details, transcripts, and private links before posting a public issue.

## Inspect commands

```bash theme={null}
pointed --help
pointed auth --help
pointed accounts --help
pointed contacts --help
pointed campaigns --help
pointed story-templates --help
pointed invites --help
pointed responses --help
pointed smart-intake --help
```