Skip to content

CLI Guide

textfsm-ai installs a textfsm-ai command with subcommands for generating templates, compiling templates into readable DSL/recognizer form, running the full sample-to-output pipeline in one shot, listing/inspecting providers, and driving the orchestrator directly.

Version

textfsm-ai --version
# or
textfsm-ai version

generate

Generate a TextFSM template (and related output) from a sample, via an LLM provider.

textfsm-ai generate sample.txt --provider openai --model gpt-4o-mini

Provider credentials are resolved in this order: CLI flag > provider-specific environment variable (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY, XAI_API_KEY, TOGETHER_API_KEY, FIREWORKS_API_KEY, CEREBRAS_API_KEY, PERPLEXITY_API_KEY, OPENROUTER_API_KEY, MOONSHOT_API_KEY, MISTRAL_API_KEY, COHERE_API_KEY, AZURE_API_KEY) > providers.yaml.

Azure additionally resolves --model (as the deployment name), --endpoint, and --api-version from AZURE_DEPLOYMENT, AZURE_ENDPOINT, and AZURE_API_VERSION the same way.

Bedrock, Vertex AI, and OCI are the exceptions to the credential rule above: none of them has a project-level API key at all.

  • Bedrock resolves --region from BEDROCK_REGION/BEDROCK_DEFAULT_REGION (or providers.yaml), and authenticates via boto3's own AWS credential chain (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN, ~/.aws/credentials, or an IAM role) — nothing AWS-secret-shaped ever passes through this CLI.
  • Vertex AI resolves --region from VERTEXAI_REGION and --project from VERTEXAI_PROJECT (or providers.yaml), and authenticates via the google-genai SDK's own Application Default Credentials chain (a service account key file via GOOGLE_APPLICATION_CREDENTIALS, gcloud auth application-default login, or workload identity) — same principle, nothing GCP-secret-shaped passes through this CLI either. Vertex AI must always be selected with --provider vertexai explicitly — it serves the same Gemini models as the native gemini provider under identical model IDs, so there's no automatic way to route between the two.
  • OCI resolves --compartment-id from OCI_COMPARTMENT_ID (or providers.yaml), and authenticates via the oci SDK's own config file at ~/.oci/config (DEFAULT profile) — the same file the OCI CLI itself uses. --region is optional for OCI: unlike Bedrock/Vertex AI it falls back to whatever region is already set in ~/.oci/config if not resolved from --region/OCI_REGION/providers.yaml. OCI must always be selected with --provider oci explicitly — its meta./xai. model-ID vendor prefixes collide with Bedrock's own re-hosted namespace, so there's no automatic way to route between the two.

Key options:

Option Purpose
--provider (required) Provider name: openai, anthropic, gemini, deepseek, groq, xai, together, fireworks, cerebras, perplexity, openrouter, moonshot, mistral, bedrock, cohere, vertexai, oci, azure
--api-key Override the resolved API key (ignored for bedrock/vertexai/oci)
--model Model name (or Azure deployment name)
--endpoint, --api-version Azure-only
--region AWS region (Bedrock), GCP location (Vertex AI), or OCI region (OCI, optional)
--project GCP project (Vertex AI only)
--compartment-id OCI compartment OCID (OCI only)
--max-retries Retry attempts (default: 1)
--template-only Print only the final TextFSM template
--records Print parsed records
--explain Print variable explanations
--handling Print LLM notes on how it handled the sample
--sample Print the input sample sent to the LLM
--raw Print the raw LLM response
--usage Print token usage
--sections Print template, records, explanations, and handling together
--json Print the full pipeline as JSON
--debug Print resolved provider/model/api-key (masked) before running

With no output flag, generate prints just the final template.

dsl

Deterministically compile a TextFSM template into its canonical form, readable DSL, and recognizer patterns — no LLM call is made.

textfsm-ai dsl template.textfsm sample.txt

TEMPLATE_FILE is a (real, valid) TextFSM template. SAMPLE_FILE is raw text; it's parsed by that template using the actual textfsm library to produce example records, which the DSL engine uses to infer each Value's type (word, digit, IP, etc.) for the canonical/readable output.

Key options:

Option Purpose
--canonical Print only the canonical TextFSM template (default)
--readable Print only the readable DSL
--recognizers Print only recognizer patterns
--sections Print canonical, readable, and recognizer sections together
--json Print the full DSL result (including the parsed AST) as JSON

With no output flag, dsl prints just the canonical template.

pipeline

Run the full pipeline in one shot: sample -> LLM-generated template -> DSL compile (canonical template, readable DSL, recognizers) -> formatted output. This is the same end-to-end flow generate and dsl cover separately, chained together and packaged per --mode (equivalent to the Python API's run_pipeline()).

textfsm-ai pipeline sample.txt --provider openai --model gpt-4o-mini
textfsm-ai pipeline sample.txt --provider openai --model gpt-4o-mini --mode debug --json

--provider/--api-key/--model/--endpoint/--api-version/--region/ --project/--compartment-id/--max-retries all resolve exactly like generate's (see above) — same credential precedence, same Bedrock/Vertex AI/OCI exceptions.

Key options:

Option Purpose
--mode Output verbosity: quiet (template or error only), default (template + readable DSL + recognizers), info (adds version/LLM-config/token usage), debug (adds the full raw generation + DSL pipeline dump). Default: default
--json Emit the selected mode's output as JSON instead of formatted text

Exit code is 0 on success and 1 if generation or DSL compilation failed — check --mode debug output for the failure detail.

list-models

List a provider's live models, fetched directly from the provider's own API (requires that provider's credentials, same as generate):

textfsm-ai list-models openai

providers

textfsm-ai providers list

NAME           DESCRIPTION
-------------  ----------------------------------------
anthropic      Anthropic Claude models
azure          Azure AI Inference / Azure OpenAI
bedrock        Amazon Bedrock (native SDK, AWS credential chain)
cerebras       Cerebras (fast open-model inference, OpenAI-compatible API)
cohere         Cohere Command models (native SDK)
deepseek       DeepSeek (OpenAI-compatible API)
fireworks      Fireworks AI (open-model hosting, OpenAI-compatible API)
gemini         Google Gemini models
groq           Groq (fast open-model inference, OpenAI-compatible API)
mistral        Mistral AI (native SDK)
moonshot       Moonshot AI / Kimi models (OpenAI-compatible API)
oci            Oracle Cloud Infrastructure Generative AI (Llama/Grok, config-file auth)
openai         Native OpenAI API
openai_compat
openrouter     OpenRouter (multi-provider model aggregator, OpenAI-compatible API)
perplexity     Perplexity (search-grounded Sonar models, OpenAI-compatible API)
together       Together AI (open-model hosting, OpenAI-compatible API)
vertexai       Google Vertex AI (Gemini via GCP, ADC credential chain)
xai            xAI Grok models (OpenAI-compatible API)


textfsm-ai providers info --name openai [--config path/to/config.yaml]
Prints the configured type and params for that provider, with sensitive keys (api_key, token, secret, password-like) masked to ***.

textfsm-ai providers test --model openai/gpt-4o-mini --prompt "Say hello" [--config path/to/config.yaml]
Sends a test prompt straight through the orchestrator to whichever provider the model routes to, and prints the raw response.

orchestrator

textfsm-ai orchestrator route --model claude-opus-4-8

Model: claude-opus-4-8
Routed provider: anthropic
Shows which provider a model would route to, without making a real call.

textfsm-ai orchestrator run --model gpt-4o-mini --prompt "Say hello" [--config path/to/config.yaml]
Runs a full orchestrator request (routing + retries + provider call) and prints the response.

Next steps