CLI Commands Reference

This page provides reference for the aip command-line interface that ships with the Python SDK. The CLI exposes the same resource coverage as the SDK, adds rich terminal renderers, and wraps import/export helpers for automation workflows.

Need the interactive slash palette cheat sheet? Head over to the CLI Slash Command Palette.

At a glance

• Manage agents, tools, MCP connections, and language models without writing code.

• Stream AI agent runs with a live TTY renderer, file uploads, and transcript capture.

• Import/export full resource definitions (JSON or YAML) and sync LangFlow flows into AIP.

• Store credentials securely in ~/.aip/config.yaml and switch output formats (rich, plain, json, md).

---

Installation & Quick start

Install & quick start

pipx install glaip-sdk

aip configure           # interactive credential prompt
export AIP_API_URL=...  # or use env vars / config set

aip status              # smoke test connectivity
aip agents list         # browse resources

Configuration sources Credentials are read from (highest precedence first) CLI flags, environment variables (AIP_API_URL, AIP_API_KEY), then ~/.aip/config.yaml. Use aip configure to create or update the config file.

---

Global options

aip [GLOBAL OPTIONS] COMMAND [ARGS]...

Global options (also honored on subcommands)

Flag	Description
--api-url TEXT	Override API endpoint (AIP_API_URL/config fallback)
--api-key TEXT	Override API key (AIP_API_KEY/config fallback)
--timeout FLOAT	Request timeout in seconds (30 default)
--view	plain (default: rich)
--json	Shortcut for --view json
--no-tty	Disable rich TTY renderer for agent runs
--version	Show CLI version
--help	Show command help

Output modes

• --view rich (default) renders tables/panels using Rich.

• --view json (or --json) emits machine‑friendly JSON.

• --view md renders Markdown; --view plain prints plain text. All subcommands accept --view/--json via the shared output_flags decorator.

---

Command Map

Command	Description
aip status	Check connectivity and resource counts
aip configure	Interactive configuration wizard (alias of aip config configure)
aip agents ...	Agent CRUD, execution, import/export, LangFlow sync
aip tools ...	Tool upload/update, metadata, script retrieval
aip mcps ...	MCP configuration management and connection tests
aip models list	View available language models
aip config ...	Manage stored credentials (list, get, set, unset, reset, configure)

---

Agents

List

aip agents list [OPTIONS]

Options:

• --simple — skip interactive fuzzy picker; always show a table

• --type TEXT — filter by agent type (config, code, a2a, langflow)

• --framework TEXT — filter by orchestration framework (langchain, langgraph, google_adk)

• --name TEXT — filter by partial name (case-insensitive)

• --version TEXT — filter by agent version

• --sync-langflow — pull latest flows from the configured LangFlow server before listing (honours LANGFLOW_BASE_URL/LANGFLOW_API_KEY)

• --view / --json — override output format

If rich output is enabled and the terminal is interactive, the command opens an in-terminal picker. Selecting an agent shows complete metadata and suggested follow-up commands (run, update, delete).

Get

aip agents get AGENT_REF [OPTIONS]

Options:

• --select INTEGER — choose among ambiguous name matches (1-based)

• --export PATH — export the full agent definition to .json or .yaml

• --view / --json

AGENT_REF accepts either an ID or a name. The command resolves ambiguity using fuzzy search or the --select flag. Exported files include agent_config, tool associations, MCP references, and metadata.

Create

aip agents create [OPTIONS]

Required flags:

• --name TEXT

• --instruction TEXT

Optional flags:

• --model TEXT — override the base model (omit to use your workspace’s AIP default); pass language_model_id inside --import payload for catalogue models

• --tools TOOL_REF — attach tools by name or ID (multi-use option)

• --agents AGENT_REF — attach sub-agents by name or ID (multi-use)

• --mcps MCP_REF — attach MCP connections by name or ID (multi-use)

• --timeout INTEGER — execution timeout per run (seconds, default 300)

• --import PATH — bootstrap from an exported agent JSON/YAML file (CLI merges CLI flags over imported data)

• --view / --json

References accept either UUIDs or human-friendly names; ambiguity raises unless unique. Import files can include metadata, agent_config (memory, tool sharing, PII tags), and runtime defaults. Secret fields should be re-supplied manually post-import.

Run

aip agents run AGENT_REF [INPUT] [OPTIONS]

Parameters:

• Positional INPUT or --input TEXT — required prompt if not provided positionally

• --select INTEGER — disambiguate name matches

• --chat-history JSON — pass prior turns as JSON array ([{"role": "user", "content": "..."}, ...])

• --file PATH — attach one or more files (repeatable)

• --timeout INTEGER — execution timeout for this run (defaults to agent timeout)

• --save PATH — persist transcript and full debug log (supports .md or .json)

• --verbose/--no-verbose — emit raw SSE JSON alongside the rich renderer

• --view / --json

The command streams SSE responses using the Rich renderer (progress panels, tool call summaries, usage stats). Captured transcripts include artifacts and timing information when --save is used. Runtime overrides such as pii_mapping, runtime_config, or per-tool settings are currently only available via SDK/REST — the CLI forwards the fixed set above.

Update

aip agents update AGENT_REF [OPTIONS]

Options:

• --name TEXT

• --instruction TEXT

• --tools TOOL_REF

• --agents AGENT_REF

• --timeout INTEGER

• --import PATH — merge updates from exported definition (CLI sanitises language model fields automatically)

• --view / --json

Updating fetches the latest copy, merges defaults, and issues a full PUT. Passing empty lists (e.g. --tools omitted) keeps current associations; supplying an empty list in an import file clears them.

Delete

aip agents delete AGENT_REF [-y/--yes]

Soft-deletes the agent after confirmation (or immediately with --yes). Use the SDK/REST to restore soft-deleted agents if needed.

Sync LangFlow

aip agents sync-langflow [--base-url URL] [--api-key KEY]

Fetches all flows from the configured LangFlow instance and upserts matching agents. Credentials fall back to LANGFLOW_BASE_URL / LANGFLOW_API_KEY environment variables.

---

Tools

List

aip tools list [--type TYPE]

• --type TEXT — filter by backend tool type (custom, native, etc.)

• --view / --json

Create

aip tools create [FILE] [OPTIONS]

Options:

• Positional FILE or --file PATH — path to the plugin Python file

• --name TEXT — override inferred plugin name (must match the class name attribute)

• --description TEXT

• --tags TEXT — comma-separated tags

• --import PATH — import metadata from exported tool definition (merges with CLI flags)

• --view / --json

If a file is provided, the CLI validates the plugin name attribute, checks for duplicates, and uploads via /tools/upload. Metadata-only creation is reserved for imports or native catalog entries.

Get

aip tools get TOOL_REF [OPTIONS]

Options:

• --select INTEGER — disambiguate by name

• --export PATH — export JSON/YAML definition

• --view / --json

Update

aip tools update TOOL_ID [OPTIONS]

Options:

• --file PATH — upload new plugin code (only valid for custom tools)

• --description TEXT — metadata update (only valid for native tools)

• --tags TEXT — comma-separated tags (native tools only)

• --view / --json

Custom tools support code updates via file upload; native tools support metadata updates. The command enforces these constraints before calling the backend.

Delete

aip tools delete TOOL_ID [-y/--yes]

Deletes the tool after confirmation. The underlying API performs a soft delete.

Script

aip tools script TOOL_ID [--view VIEW]

Fetches and prints the stored plugin source (json view wraps it under {"script": ...}).

---

MCPs (Model Context Protocol)

List

aip mcps list

Shows stored MCP connections.

Create

aip mcps create --name NAME --transport TRANSPORT [OPTIONS]

Options:

• --description TEXT

• --config JSON — inline JSON payload (e.g. '{"url": "https://..."}')

• --view / --json

Get

aip mcps get MCP_REF [--export PATH] [--view VIEW]

Resolves names/IDs, optionally exports the definition.

Tools

aip mcps tools MCP_REF

Lists tools discovered from a stored MCP connection.

Connect (ad-hoc test)

aip mcps connect --from-file CONFIG.json

Loads JSON config from disk, calls /mcps/connect, and prints the result. Uses Rich panels unless --view json is active.

Update

aip mcps update MCP_REF [OPTIONS]

Options:

• --name TEXT

• --description TEXT

• --config JSON

• --view / --json

The underlying SDK escalates to a full PUT when name, transport, and config are supplied together; the CLI currently exposes name, description, and config, so updates are submitted as partial PATCH requests.

Delete

aip mcps delete MCP_REF [-y/--yes]

Soft-delete after confirmation.

---

Language Models

aip models list [--view VIEW]

Displays available language models for the current API key, including provider and optional base URL overrides. Use this list to locate language_model_id values for agent creation.

---

Configuration & Status

Interactive setup

1

Prompt for API URL and key

The wizard prompts for API URL and key (with masked input).

2

Persist to disk

Persists values to ~/.aip/config.yaml (0600 permissions).

3

Test the connection

Tests the connection by listing agents/tools/MCPs.

Config command group

aip config list

Shows stored values with masked API keys.

Other subcommands:

• aip config set KEY VALUE — currently supports api_url, api_key

• aip config get KEY

• aip config unset KEY

• aip config reset [--force]

Status

aip status

Displays the active configuration sources (file/env/CLI), pings the API, and counts agents/tools/MCPs. Useful for smoke tests in CI.

---

Import & Export Workflow Tips

• Use aip agents get <ref> --export agent.yaml or aip tools get <ref> --export tool.json to version configurations alongside code.

• Imported agent files can carry agent_config settings for memory scopes, PII mappings, and tool output sharing described in the AIP REST reference. The CLI sanitises language model fields so you can swap between named models and catalogue IDs safely.

• aip agents run ... --save transcript.md captures the Rich stream plus final answer; JSON saves include captured debug events for replaying pipelines.

• When scripting, prefer --view json to capture machine-friendly responses and avoid control characters from the Rich renderer.

---

Examples

Run an agent with attachments and save the transcript

Run an agent with attachments

aip agents run agent-123 \
  "Summarise the incident and propose mitigation" \
  --file incident-report.pdf \
  --timeout 900 \
  --save incident-summary.md

Replace agent-123 with the ID you captured from aip agents list.

Import agent configuration from Git

Import agent from repo

# Assuming agent.yaml lives in your repo
aip agents create --import agent.yaml --name "prod-coordinator"

Sync LangFlow and inspect

Sync LangFlow and inspect (JSON view)

export LANGFLOW_BASE_URL=https://flows.example.com
export LANGFLOW_API_KEY=lfk-123

aip agents list --type langflow --sync-langflow --view json | jq '.[] | {id, name, metadata}'

---

Related documentation

• Python SDK Reference — low‑level control with code

• REST API Reference — authoritative endpoint catalogue

The CLI shares the same backend guarantees as the Python SDK. Consult the REST reference for the full payload schema.