Datafast CLI for AI Agent Tools: Workflow, Artifacts, Handoffs

Most analytics software is designed for eyeballs.

That is fine if a human analyst is sitting in a dashboard, clicking around, taking screenshots, and narrating what they think they saw. It is weak if the consumer is an agent.

If you care about ai agent tools, the useful question is not whether an analytics product has pretty charts. The useful question is whether an agent can query it deterministically, save the result as an artifact, hand it to another system, and recover cleanly when something breaks.

That is the real reason Datafast matters in our stack.

This note is not the build story for the CLI. That already exists in How to Build CLI Tools That AI Agents Can Actually Use, and the shipped tool lives at /drops/datafast-cli. This page is the operator manual that comes after the tool exists: the actual command order, the artifact discipline, the failure modes, and the handoff logic that make the workflow usable in production.

If you want broader system context, pair this with OpenClaw in the AI Developer Tools Stack, AI Developer Tools in Production: How We Run Starkslab as a Human + Agent Operating System, Inbox to Execution, and Build Your First Real Agent Step by Step.

Why are dashboards weak for ai agent tools workflows?

Dashboards optimize for a human standing in front of a screen. Agents need something else entirely.

A dashboard gives you:

• hidden state in filters and date pickers,
• visual aggregation that is hard to diff,
• no stable file artifact by default,
• weak error semantics,
• and no natural handoff format.

That is not a moral failing. It is just a mismatch.

When an agent uses a dashboard, the workflow usually degrades into one of three bad patterns:

1. browser automation against brittle UI controls,
2. screenshot interpretation,
3. or copy-paste from a human operator back into chat.

All three are expensive. All three lose precision. All three make post-run auditing harder than it should be.

A dashboard card that says “25 visitors in 30 days” looks fine to a human. But an agent also needs to know:

• which exact window produced that value,
• whether the data is raw or normalized,
• whether hostnames were merged,
• where the output should be stored,
• and what downstream tool should consume it next.

That is why the better design rule for analytics inside ai agent tools is boring and strict:

• explicit commands,
• explicit flags,
• explicit output format,
• explicit files on disk,
• explicit stderr when something fails.

Boring wins here. The moment you want a telemetry step to plug into a morning brief, a weekly SEO review, or a patching loop, “I can click around and inspect it” stops being enough.

This is also consistent with the current platform guidance from Anthropic’s tool-design note and OpenAI’s practical guide to building agents: tools work better when their contracts are narrow, parseable, and observable.

Why does CLI + JSON make Datafast usable as one of the ai agent tools?

Datafast becomes agent-usable the moment the interface is reduced to something an operator can inspect and a machine can trust:

datafast overview --period 30d --json

That single line has almost everything a dashboard click-path usually hides:

• the command surface,
• the time window,
• the expectation of structured output,
• and the ability to redirect the result into a file.

For example, the 30-day Starkslab overview snapshot is just a saved JSON artifact:

datafast overview --period 30d --json \
  > starkslab/keyword-data/deep-seo-2026-03-11/datafast-overview-30d.json

And the payload is unglamorous in exactly the right way:

{
  "status": "success",
  "data": [
    {
      "visitors": 25,
      "sessions": 42,
      "bounce_rate": 73.81,
      "avg_session_duration": 14142.86,
      "revenue": 0,
      "conversion_rate": 0,
      "currency": "$"
    }
  ]
}

That is what you want from analytics in an agent stack. Not narrative. Not decoration. Just a stable object.

Once output is JSON, the tool becomes composable. A human can inspect it. An agent can summarize it. Another CLI can transform it. A weekly report can archive it. A handoff package can reference it by path.

You can also do normal operator things without opening a browser:

jq '.data[0] | {visitors, sessions, bounce_rate}' \
  starkslab/keyword-data/deep-seo-2026-03-11/datafast-overview-30d.json

That is the deeper point. Good ai agent tools are not magical because they are “AI-native.” They are useful because they are machine-readable first and human-readable second.

The Datafast CLI also inherits the default strengths of the terminal as a tool boundary:

• stdout for results,
• stderr for failure,
• exit codes for control flow,
• files as durable artifacts,
• shell composition for downstream steps.

A chart cannot be redirected into a file with semantic meaning. A CLI response can.

What is the real Datafast workflow we run on Starkslab?

The command order matters more than people think.

We do not start with top pages because that invites premature storytelling. We do not start with timeseries because it is too granular before we know the overall shape. We do not start with referrers because source mix is only meaningful after we understand the site envelope.

The practical Datafast workflow is:

overview -> top pages -> referrers -> timeseries

That sequence is not theoretical. It is the order we use because each step narrows the next question.

1) Overview first: get the envelope before the story

The first pass is always the same three windows:

datafast overview --period 30d --json > datafast-overview-30d.json
datafast overview --period 7d --json  > datafast-overview-7d.json
datafast overview --period yesterday --json > datafast-overview-yesterday.json

Those three files tell us whether we are looking at:

• a site-level trend problem,
• a recent anomaly,
• or a normal low-volume period that does not justify overreaction.

For the current Starkslab snapshot, the three windows look like this:

{
  "30d": {"visitors": 25, "sessions": 42, "bounce_rate": 73.81},
  "7d": {"visitors": 10, "sessions": 20, "bounce_rate": 80},
  "yesterday": {"visitors": 3, "sessions": 4, "bounce_rate": 75}
}

That gives an operator a clean first read:

• traffic is still early-stage and sparse,
• the last 7 days account for a large share of the 30-day footprint,
• and “yesterday” is not wildly out of family.

That is enough to keep us from doing stupid analysis. The workflow starts with envelope control.

2) Top pages second: find where traffic actually lands

Once the envelope is understood, we move to page distribution:

datafast top --type pages --period 30d --limit 30 --json \
  > datafast-top-pages-30d.json

The useful part of the current artifact is not just the winners. It is the shape of the traffic plus the reporting quirks:

[
  {"hostname": "starkslab.com", "path": "/", "visitors": 17},
  {"hostname": "www.starkslab.com", "path": "/", "visitors": 5},
  {"hostname": "starkslab.com", "path": "/notes", "visitors": 4},
  {"hostname": "starkslab.com", "path": "/login", "visitors": 4},
  {
    "hostname": "starkslab.com",
    "path": "/notes/openclaw-self-modification-how-agents-rewrite-themselves",
    "visitors": 4
  }
]

This is where CLI output beats dashboard vibes.

A dashboard card might tempt you to say “homepage dominates” and move on. The JSON artifact shows something more useful:

• apex and www are both present,
• the homepage is split across hostnames,
• /notes and /login are meaningful early pages,
• one specific note is already pulling attention.

That hostname split matters. If you do not see it, you overfit the wrong story. With a file artifact, you can normalize it explicitly instead of pretending it was never there:

jq '[.data[] | {path, visitors}] 
    | group_by(.path) 
    | map({path: .[0].path, visitors: (map(.visitors) | add)})' \
  starkslab/keyword-data/deep-seo-2026-03-11/datafast-top-pages-30d.json

This is the kind of mundane cleanup step dashboards discourage and operators actually need.

3) Referrers third: identify acquisition mix without hand-waving

After page distribution, we inspect where sessions are coming from:

datafast top --type referrers --period 30d --limit 20 --json \
  > datafast-top-referrers-30d.json

The current Starkslab referrer mix is tiny but legible:

[
  {"referrer": "Direct/None", "visitors": 18},
  {"referrer": "X", "visitors": 4},
  {"referrer": "Google", "visitors": 3}
]

That tells us three practical things immediately:

• direct traffic still dominates,
• distribution on X matters more than search at this stage,
• and Google exists, but it is not yet carrying the system.

That is useful in an operator loop because it changes the next decision. If Google were already dominant, we might spend the next hour on query segmentation. With this mix, the better move is usually:

• keep publishing strong note infrastructure,
• tighten internal linking,
• improve discoverability without pretending search is already mature.

Again, no dashboard philosophy needed. Just one file with stable keys.

4) Timeseries last: place the changes in time

Only after overview, pages, and referrers do we look at the time curve:

datafast timeseries --period 90d --interval week --json \
  > datafast-timeseries-90d-week.json

The current weekly series is exactly the kind of output an agent can summarize without embellishment:

[
  {"timestamp": "2026-02-06T00:00:00+01:00", "visitors": 4, "sessions": 5},
  {"timestamp": "2026-02-13T00:00:00+01:00", "visitors": 10, "sessions": 13},
  {"timestamp": "2026-02-20T00:00:00+01:00", "visitors": 2, "sessions": 3},
  {"timestamp": "2026-02-27T00:00:00+01:00", "visitors": 10, "sessions": 10},
  {"timestamp": "2026-03-06T00:00:00+01:00", "visitors": 8, "sessions": 18}
]

That series does not scream “hockey stick.” Good. It should not.

What it does show is more useful:

• activity is recent,
• there are early spikes worth correlating with shipping moments,
• and sessions are improving even when raw visitors stay small.

This is where boring structured output beats magical dashboards. The timeseries is not trying to persuade you. It is just a list of dated facts.

How does this Datafast workflow plug into Starkslab morning and weekly loops?

The Datafast sequence becomes valuable when it is treated as a telemetry lane inside the wider Starkslab operating system.

The morning loop is lightweight. It is not a full diagnosis. It is a state read with explicit artifacts:

datafast overview --period yesterday --json \
  > starkslab/keyword-data/deep-seo-2026-03-11/datafast-overview-yesterday.json

datafast overview --period 7d --json \
  > starkslab/keyword-data/deep-seo-2026-03-11/datafast-overview-7d.json

datafast top --type pages --period 30d --limit 30 --json \
  > starkslab/keyword-data/deep-seo-2026-03-11/datafast-top-pages-30d.json

That gives the operator enough to answer three questions before lunch:

• Did anything obviously drift?
• Which pages deserve attention?
• Are we looking at a distribution issue or a search issue?

The weekly loop is heavier and uses the full sequence:

datafast overview --period 30d --json

datafast top --type pages --period 30d --limit 30 --json

datafast top --type referrers --period 30d --limit 20 --json

datafast timeseries --period 90d --interval week --json

From there, the output gets handed into the decision system described in Inbox to Execution. The important part is that the handoff is file-based, not conversational.

A minimal machine-readable handoff package looks like this:

{
  "workflow": "datafast-weekly-review",
  "artifacts": [
    "datafast-overview-30d.json",
    "datafast-top-pages-30d.json",
    "datafast-top-referrers-30d.json",
    "datafast-timeseries-90d-week.json"
  ],
  "next_action": "review internal linking and keep publishing workflow-heavy notes",
  "notes": [
    "normalize apex/www views in analysis",
    "direct still dominates over Google"
  ]
}

That package is boring. Good. A boring handoff is what lets another agent, a future you, or a weekly review script consume the result without guesswork.

This is the real operator value of Datafast inside ai agent tools: it turns telemetry into transferable artifacts instead of one-off interpretations.

What artifact discipline keeps this workflow trustworthy?

The difference between “I checked analytics” and “the system can use analytics” is almost entirely artifact discipline.

When we run this workflow, we do not treat the terminal output as the result. The terminal output is just the transport layer. The result is the artifact set on disk, with filenames that make the time window and intent obvious.

A clean bundle looks like this:

starkslab/keyword-data/deep-seo-2026-03-11/
  datafast-overview-yesterday.json
  datafast-overview-7d.json
  datafast-overview-30d.json
  datafast-top-pages-30d.json
  datafast-top-referrers-30d.json
  datafast-timeseries-90d-week.json

That folder is more valuable than any dashboard bookmark because it can survive handoffs. It can be attached to a note brief. It can be referenced in a weekly review. It can be re-read after a patch. It can be diffed against a later run. It can also be ignored until needed, which is underrated. Good artifacts reduce cognitive load because they let you defer interpretation without losing state.

We keep three rules around these files.

Rule 1: keep the raw output. Do not save only the summary. A summary is opinion. The raw JSON is evidence.

Rule 2: keep the window in the filename. overview.json is almost useless after a week. datafast-overview-30d.json tells you what you are looking at before you open it.

Rule 3: keep downstream notes separate from upstream data. Once you start mixing summaries into the same file as the snapshot, replay gets harder and error analysis gets sloppy.

In practice, that means the workflow often looks like this:

mkdir -p starkslab/keyword-data/deep-seo-2026-03-11

datafast overview --period 30d --json \
  > starkslab/keyword-data/deep-seo-2026-03-11/datafast-overview-30d.json

datafast top --type referrers --period 30d --limit 20 --json \
  > starkslab/keyword-data/deep-seo-2026-03-11/datafast-top-referrers-30d.json

Then, and only then, do we derive a memo, a brief, or a recommendation.

This matters because operator mistakes are usually sequencing mistakes. People summarize too early. They see one graph, form a story, and then use the rest of the workflow to confirm the story they already wanted. File-first analytics slows that down in a good way.

It also makes handoffs cleaner. If a future pass needs to ask, “Why did we decide search was secondary here?” the answer is not buried in a chat transcript. It is recoverable from the artifact bundle:

• overview shows tiny absolute traffic,
• top pages shows homepage and note concentration,
• referrers shows direct outrunning Google,
• timeseries shows recent but uneven activity.

That chain of evidence is what allows a later system to inherit the decision without inheriting the original conversation.

This is also why I would not describe Datafast as “analytics for agents” in the abstract. That framing is too soft. The practical value is narrower and stronger: it is analytics that can be saved, replayed, normalized, and handed off without turning into prose first.

What broke when we battle-tested the workflow?

The happy path is not the point. The workflow becomes credible when the failure path stays legible.

The best example is the old Datafast error formatting bug. During stress testing, an invalid request produced this:

$ datafast visitors nonexistent-id
API error (400): [object Object]

That message is survivable for a human and terrible for an agent.

A human reads it and infers “the request was bad.” An agent gets almost nothing:

• no structured error body,
• no actionable message,
• no clue whether the problem was auth, params, or upstream state.

The fix was not glamorous. It was just correct error serialization. After the patch, the same class of failure becomes useful:

$ datafast visitors nonexistent-id
API error (400): {"code":400,"message":"Invalid visitorId format"}

That single improvement changes the whole operator experience. Now the tool can:

• stop with a meaningful stderr record,
• preserve machine-readable context,
• and let the calling agent decide whether to retry, skip, or report.

There was another useful failure in the stress pass: API 400s on unsupported combinations. For example, a timeseries call with an invalid parameter combination should not be treated as mysterious model behavior. It should terminate cleanly and leave evidence.

That is the practical lesson: robust ai agent tools do not eliminate failure. They turn failure into something parseable.

The same goes for normalization. The top-pages snapshot exposed traffic split between starkslab.com and www.starkslab.com. That is not a dramatic bug, but it is exactly the kind of data-shape problem dashboards blur away. In a file-based workflow, you can normalize downstream, document the assumption, and keep the artifact trail intact.

Why does boring structured output beat magical dashboards here?

Because the real work is not looking at analytics. The real work is what happens next.

At Starkslab, telemetry only matters if it can feed:

• a morning brief,
• a weekly SEO review,
• an artifact bundle,
• a patch decision,
• or a handoff into a broader operating loop.

A dashboard can help a human notice something. A CLI + JSON workflow can help a system act on it.

That is why this page sits next to notes like the Starkslab operating system, the OpenClaw stack, and the Minimal Agent Framework drop. The useful unit is not “tool with analytics.” The useful unit is a tool that can survive composition.

Datafast is valuable because it is simple enough to trust:

• command in,
• JSON out,
• artifact on disk,
• stderr when it breaks,
• handoff package when it is done.

That is not flashy. It is better.

If you are building your own stack of ai agent tools, this is the design rule I would copy first: make telemetry queryable from the terminal, make every result storable as JSON, and make the failure path as explicit as the success path. Pretty dashboards are nice. Deterministic workflows compound.

External references

• DataFast: https://datafa.st
• Anthropic — Writing tools for agents: https://www.anthropic.com/engineering/writing-tools-for-agents
• OpenAI — A practical guide to building agents: https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf
• jq manual: https://jqlang.org/manual/