> ## Documentation Index
> Fetch the complete documentation index at: https://docs.os.meetluno.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI for agents

> How coding agents use the Luno OS CLI.

Luno OS is built for coding agents. The `luno` CLI works headlessly out of the box: every command runs non-interactively, invoke and inspect commands print JSON, and the docs are a command away so your agent can learn how Luno OS works as it builds.

This page covers agent-specific behavior. For installation and the full command list, see the [CLI reference](https://docs.os.meetluno.ai/cli.md).

## Recommended path

When your coding agent runs in an editor on your machine — Cursor, Claude Code, VS Code, and similar — **use the CLI and a local project**. That is the path we recommend today: ordinary git and tests, the full deploy-and-debug loop on this page, and the most stable agent experience.

Set up with [AI onboarding](https://docs.os.meetluno.ai/build-with-ai/onboarding.md) or hand your agent [start.md](https://os.meetluno.ai/start.md).

The [Luno OS MCP server](https://docs.os.meetluno.ai/build-with-ai/mcp-for-agents.md) is for chat-first agents when you cannot or do not want a local install. It targets the same platform, but the hosted-workspace MCP path is newer and less battle-tested than the CLI.

There is also a third surface that needs no coding agent at all: [Luno Builder](https://docs.os.meetluno.ai/build-with-ai/platform-agent.md), a built-in building agent in the Luno OS web app. It runs this same CLI in a hosted session against your project's shared draft.

## Baseline context and docs

`luno init` scaffolds an `AGENTS.md` guide (symlinked to `CLAUDE.md`) with concise baseline context — the CLI, project layout, discovery, and working habits — that most coding agents read automatically. The CLI keeps `AGENTS.md` in sync with your installed version whenever you run a command in the project. Use [`luno docs search`](https://docs.os.meetluno.ai/cli#docs) and [`luno docs query`](https://docs.os.meetluno.ai/cli#docs) for deeper reference.

For anything deeper, your agent reads the docs directly from the CLI — no auth, no project required:

```bash theme={null}
luno docs search "webhook trigger"      # find pages by topic
luno docs query "cat /quickstart.mdx"   # read a page by path
```

> **[Docs for agents](https://docs.os.meetluno.ai/build-with-ai/docs-for-agents.md)**
>
> How your agent searches and reads the Luno OS docs while it builds.

## A deploy-first build loop

Most agent work follows one loop: edit `src/` (or sync the shared draft), deploy to your platform project, then run and inspect what's deployed with the CLI. Deploy often. Managed-Git deploys analyze the pinned draft locally — use `--accept-impact` when running a filtered deploy non-interactively if its impact expands or is unknown.

Before wiring in an integration, run `luno credentials list` and try it once against the intended account: `luno integrations execute` for a **custom MCP** remote tool (`{org}/{name}`), or a thin workflow (`luno workflows run <slug> --wait` after deploy) for an official app action from its `@meetluno/integration-*` package. This catches missing permissions and account-specific IDs before they are embedded in an agent or workflow.

**Do not run lint, typecheck, or build as separate steps before deploy** — `luno deploy` runs its own gates and build. The one exception is saving to the shared draft (`luno/draft`) from a hosted session: run `luno typecheck` first, since a type error on the shared draft breaks it for everyone before any deploy gate runs.

```bash theme={null}
luno deploy --project <id>                 # preflight, build, upload, and activate
luno deploy --accept-impact --filter workflows/ping --project <id>
luno workflows run greeting --input '{"name":"Ada"}' --wait --timeout 60
luno agents prompt support --message "Hi" --wait --timeout 120
luno integrations execute my-org/example-mcp list_accounts --input '{}'  # custom MCP remote tool
```

Use `luno test` when you want a fast local loop on unit or integration tests — it is not a deploy prerequisite.

Prefer bounded `--wait` calls over shell `sleep` loops. The agent chooses the duration with `--timeout <seconds>`. A timeout exits successfully with the latest running state; it does not mean the run failed. Continue other independent work or wait again with the corresponding `runs get` or `sessions get` command.

After a deploy, runtime commands target that project automatically — your agent has no config to manage. Keep work-in-progress out of deploys with `@luno ignore` (see [deploy individual files](https://docs.os.meetluno.ai/learn/projects/deploy-individual-files.md)).

`integrations execute` resolves credentials like the runtime does — project default → org default. In a linked project the project scope resolves automatically; otherwise pass `--project <slug>`. Pin a specific instance (and the only way to use a user credential) with `--credential <slug>`; see [Actions](https://docs.os.meetluno.ai/cli.md#actions).

If the project already exists but its code isn't on this machine, `luno pull --project <slug>` fetches the shared draft (`luno/draft`) into the directory (or merges it into an existing clean checkout) and installs dependencies. Pass `--published` for the active deploy revision instead.

## Headless mode

Every command runs without prompts, so agents and CI never block on input.

* `luno init my-app --yes` skips all prompts. The CLI also goes headless automatically in a non-TTY environment (piped output, CI runner).
* Destructive commands require explicit confirmation via `-y, --yes` instead of an interactive prompt:

```bash theme={null}
luno init my-app --yes
luno projects delete --project my-app --yes
luno api-key revoke <id> --yes
```

If a required value is missing in headless mode, the command exits with an error describing what's needed rather than waiting for input.

## Machine-readable output

Invoke and inspect commands (`workflow`, `agent`, `trigger`, `history`, `credentials`, `health`, and friends) print JSON to **stdout** so your agent can parse results directly. No flag is needed; JSON is the default for these commands.

```bash theme={null}
luno workflows run greeting --input '{"name":"Ada"}' | jq '.runId'
```

Errors are written to **stderr**, and the process exits non-zero on failure:

| Outcome | Exit code | Stream |
| - | - | - |
| Success | `0` | JSON on stdout |
| Wait timeout (still running) | `0` | Latest JSON state on stdout; continuation hint on stderr |
| Failure | `1` | Error message on stderr |

Lifecycle commands (`init`, `build`, `deploy`) print human-readable status instead; they drive your project rather than return data.

## Injecting secrets from the environment

Agents should never hardcode secrets. When setting a credential, read the value from an environment variable with `@env:`:

```bash theme={null}
luno credentials create exa --scope org --set apiKey=@env:EXA_API_KEY
```

`--set key=@env:VAR` reads `VAR` from the shell, falling back to the project's `.env` when it isn't set in the environment. Use `--set key=value` only for non-sensitive literals.

`@env:` only works where the secret already exists in the environment — a local shell or CI. In hosted sessions (Luno Builder, MCP), there is no user `.env`; connect the app instead with `luno connect <slug> --print-url` and let the user complete the flow, or have the user add the key through the Integrations page.

## Move or copy credentials across scopes

Prefer these over creating a second connection when the secret or OAuth account already exists:

```bash theme={null}
# Move in place (same id) — single destination scope
luno credentials update <credential-id> --scope project --project-slug production
luno credentials update <credential-id> --scope org

# Copy into new scopes (default name: "{label} (copy)")
luno credentials duplicate <credential-id> --scope org --scope project --project-slug staging
```

You must be allowed to manage the source and access the destination (project membership for project targets; user scope is always the authenticated user). Full detail: [change scope](https://docs.os.meetluno.ai/learn/credentials/connect-credentials.md#change-a-credentials-scope) and [duplicate](https://docs.os.meetluno.ai/learn/credentials/connect-credentials.md#duplicate-a-credential).

## Headless OAuth

Connecting a provider opens a browser by default. In a headless environment, print the authorize URL instead so it can be handed to a human to complete:

```bash theme={null}
luno connect google --print-url
```

## Closing the loop

After invoking a workflow or agent, wait for it with a concise summary, then request richer detail only when you need it:

```bash theme={null}
luno workflows runs get greeting <run-id> --wait --timeout 60 --summary
luno workflows runs get greeting <run-id> --field output
luno workflows runs get greeting <run-id> --include steps,trace,children

luno agents sessions get support <session-id> --wait --timeout 120 --summary
luno agents sessions get support <session-id> --include messages,trace
luno history list --kind workflow --status failed
```

`--summary` and `--field` avoid digging through nested envelopes. `--include` pulls in steps, messages, events, and traces when you need the same visibility you'd get in the web app. Workflows use durable **runs**; agents use durable **sessions**.

## Report build friction

The Luno OS team cannot see errors, confusion, or workarounds inside a local coding session. When your agent encounters unclear docs, confusing CLI behavior, unexpected framework constraints, repeated trial and error, or missing capabilities, it should send a short report after completing the work and before its final response:

```bash theme={null}
luno feedback create --message "$(cat <<'EOF'
*Quick Recap and Context*

I was building…

-------------------------

*Feedback for Luno OS Team*

*1. Short title*
What happened, what was confusing or missing, how I resolved it, and what Luno OS could improve.
EOF
)"
```

The command requires authentication and an active organization. The report body is freeform, and the platform adds the signed-in user's identity and organization automatically. Reports should read like a note to a team member with zero context: plain language first, one numbered item per issue, technical detail after the plain explanation — `luno feedback create --help` prints the full writing guide. Do not include secrets, credentials, private source dumps, proprietary code, or personal data from project files or user inputs.

Your agent does not need to mention the report in its response to you unless you ask. See [`feedback create`](https://docs.os.meetluno.ai/cli#feedback) for the command reference.

## Authentication and CI

On your own machine, deploying and invoking a deployed project require a one-time browser login:

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

The token is stored in your operating system's secure credential store and reused on every subsequent command, so an agent that runs after you've logged in can deploy and operate cloud projects without re-authenticating.

Hosted sessions never log in: the in-app [Luno Builder](https://docs.os.meetluno.ai/build-with-ai/platform-agent.md) and [MCP](https://docs.os.meetluno.ai/build-with-ai/mcp-for-agents.md) workspaces already have API credentials injected, and `luno auth login` would fail there (it needs a browser). If a command in a hosted session reports missing auth, that is an environment problem to surface, not a login to run.

> **[CLI reference](https://docs.os.meetluno.ai/cli.md)**
>
> Every command and flag.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.