@0x26/amp

Ampersand CLI

Commands: login, schema, ask, and skill. Requires Node.js 20 or later.

npm install -g @0x26/amp
amp login --store https://YOUR-TENANT-STORE --install-skill
amp login --status
amp schema
amp ask "What data is available to me?"

Your administrator supplies the tenant store URL. Browser sign-in authorizes data access; installing the package does not grant access. Ask must be enabled for your tenant.

• amp schema [type]: authorized object types and columns for scoping a question.
• amp ask "question": answer, evidence, and limitations; --help lists conversation controls.
• amp login --logout: remove the selected local session. It does not revoke sessions on other devices.
• amp --profile <name> ...: select a saved tenant; use login --name <name> when signing in.

Credentials are stored under ~/.config/amp with user-only permissions. The skill is bundled as skill/SKILL.md; the setup flag installs it under ~/.claude/skills/amp-cli/SKILL.md. For other agent environments, use the skill installation commands below. Do not include credentials in skill files.

For a package archive supplied by your administrator, install with npm install -g ./amp-customer-VERSION.tgz, then follow the same login steps.

Use npm install -g @0x26/amp@VERSION for a reviewed update. Ask answers include limitations; do not treat an incomplete result as a complete data export.

Use amp ask for exact counts, joins and export requests. Specify the fields, filters and time range you need, and check the returned evidence and completeness limits. The customer CLI no longer provides amp sql; existing scripts that use it must move to Ask. An answer or conversation transcript is not a full dataset export. The removal takes effect after installing a CLI release containing this change; refreshing the skill alone does not remove SQL from an older installed binary.

Humans and agents

• In a terminal, results are readable previews. Piped output defaults to agent JSON. Ask still streams progress on stderr unless --agent or --quiet is explicit.
• --agent: one { "data": ..., "meta": { "version": 1, ... } } response; no prompts or routine progress. Errors return { "error": { "code", "message", "retryable", "next_command"? } } and a nonzero exit code.
• --human: force readable output. --quiet: hide routine progress. --no-input: never start browser sign-in or wait for input.
• --json: preserve the original raw JSON shape for existing scripts. Select one output mode per command.
• amp schema --out <file> saves schema metadata and prints a receipt; agent mode writes an envelope to both the file and the receipt. Ask writes its structured answer to stdout with --json.
• Agent mode changes output, not identity or permissions. A person signs in; their local agent uses the same authorized session.

amp --agent login --status
amp --agent schema
amp --no-input ask --json 'Give the exact record count by day for the past week, and flag incomplete coverage.'
amp --human ask 'What data is available to me?'
# Install the skill separately, without browser sign-in:
amp skill install --harness codex

The default skill destination is Claude Code. Use amp skill install --harness codex for Codex's persistent skill and session hook. Review and trust the hook before it runs; until then, sync and reread the installed skill manually before Ask. Use amp skill install --dir <directory> for another harness's skill directory and arrange session-start sync. Existing hand-edited skill files are preserved. Read the installed skill to continue in the current chat; it also persists for future sessions.

Ask answers include numbered sources and limitations. When the workspace has evidence links configured, minute sources include a URL to the supporting entry. “Preview unavailable” keeps the original source reference without a link. Use amp --no-input ask --json "<question>" for progress and a structured final answer with evidence and preview metadata. Use amp --agent ask "<question>" when you explicitly want a quiet, final-only response.

Ask uses your signed-in account for “me” and your computer's timezone for “today”. Override the timezone with amp ask --timezone America/Los_Angeles "My activity today". Your workspace needs an Ask service that supports timezone context. Sources and available evidence URLs appear below human-readable answers; structured output retains the evidence metadata. A source can lack a preview when no supporting minute entry is available.

For deeper research, set limits on a new question or conversation follow-up:

amp ask "Find recurring workflow inefficiencies" --max-model-turns 500 --max-research-seconds 2700 --max-frame-reads 480

Model turns are shared by the main investigator and its delegates; screenshot analysts, progress generation and answer finalization are excluded. Frame reads are shared across the request. Research duration remains within the one-hour server request timeout. Omitted flags keep service defaults. These flags require an Ask service that supports request limits and cannot be used with --watch, --cancel, or --transcript. --max-wait changes only how long the CLI waits for an answer.

Expanded reports require both the updated Ask service and CLI. Ordinary requests retain the existing output allowance. Raising --max-answer-bytes permits larger reports within a 1 MiB event envelope; the service still bounds the full conversation transcript at 4 MiB. Internal operations include screenshot processing and source checks as well as model calls. operation_limit identifies exhaustion; increase --max-operations for the next run. --max-submission-repairs 0 disables repairs after the initial submission.

Reading Ask answers in your terminal

Interactive terminals open an answer reader with Sources and Limitations collapsed. Use arrow keys to scroll, Enter to expand a section or open a source, s/l to toggle sections, and q or Ctrl-C to close the reader. Supported terminals also allow clicking section rows and citations. Inline [1] references use terminal hyperlinks; your terminal may require its normal link modifier. Expanded sources retain full URLs for copying when hyperlinks or browser launching are unavailable.

Use amp ask --plain "question" for the full printable answer and sources without the reader. Piped output, --json, and --agent keep their existing formats. The reader requires both terminal input and output and is disabled for TERM=dumb. Closing it leaves a compact answer and a command for replaying full source URLs.

Install once, refresh published instructions

Your administrator supplies the Ask service origin (distinct from the ontology store URL). Install a small bootstrap once:

amp skill install --service https://YOUR-ASK-SERVICE
# Or choose the skill directory your agent reads:
amp skill install --service https://YOUR-ASK-SERVICE --dir ~/.agents/skills/amp-cli
amp --agent skill fetch --service https://YOUR-ASK-SERVICE

The bootstrap fetches /skill.md directly on first use in a chat. There is no ontology lookup or authentication for this public, generic instruction file. Skill changes ship with Ask deployments, independently of CLI releases. Existing chats retain their loaded instructions until explicitly refreshed. Changes to CLI capabilities or bootstrap discovery still require an update.

Fetch has a five-second deadline and 64 KiB limit, refuses redirects, and sends no credentials. It revalidates a publisher-scoped cache with ETags; offline or older services fall back to the last valid cached skill, then the bundled skill. Agent output reports source, stale, version (SHA-256), and any warning. Hand-edited local skills are preserved. Installation without --service retains the bundled, offline skill behavior.

Installing to the Claude Code default location (amp skill install or amp login --install-skill, without --dir/--skill-dir) also adds a SessionStart hook to ~/.claude/settings.json for new and cleared sessions. It runs amp --agent skill sync, which installs the latest @0x26/amp when the registry has a newer version, refreshes the installed skill (the updated binary does this after an upgrade), and pre-fetches the published skill when one is configured. The hook is added once, other settings are preserved, and an unparseable settings file is left untouched. AMP_NO_UPDATE_CHECK=1 skips the version check. Other agents can run amp --agent skill sync --dir <skill-dir>. amp login --install-skill --skill-service https://YOUR-ASK-SERVICE installs the refreshing skill during sign-in.

Related follow-ups and corrections automatically use the current Amp conversation under the skill instructions. Agent Ask output includes meta.continuation with command arguments, profile, store, and conversation ID. Append the question as one argument; never concatenate it as shell code. Keep this state in the current chat, not a machine-wide “last conversation.” Presentation-only edits need no new Ask. Raw --json output remains unchanged. This guides agent routing; it does not force arbitrary LLMs to follow instructions or guarantee behavior after lost context.