@microtica/cli

The official command-line interface for operating Microtica from a terminal, shell script, CI job, or coding agent. The executable is named microtica.

It covers projects, environments and infrastructure resources, Kubernetes apps, Git integrations, pipelines and components, combined deployment history, and normalized logs.

Requirements and installation

• Node.js 18 or newer
• A token generated from the Microtica Console

Install globally for interactive use:

npm install --global @microtica/cli
microtica --version

Or run a pinned version without a global install:

npx --yes @microtica/[email protected] --help

For CI, pin the package version in package.json or in the npx command to avoid taking an unreviewed CLI update during a deployment.

Authentication

Generate a token in the Microtica Console, then provide it to the CLI:

# Argument form (visible to the process list on some systems).
microtica login --token "$MICROTICA_TOKEN"

# Stdin form.
printf '%s' "$MICROTICA_TOKEN" | microtica login

Stored credentials live at ~/.microtica/credentials and are written with mode 0600. Environment variables take precedence and are usually preferable in CI:

| Variable | Meaning | | --- | --- | | MICROTICA_TOKEN | Token generated from the Microtica Console. Overrides the stored credential. | | MICROTICA_PROJECT_ID | Default project ID for project-scoped commands. |

Verify the credential and API connection:

microtica whoami --json

If an operation returns an authentication error, generate a token in the Microtica Console and log in again.

Project selection

Most commands need a project. Set it once:

export MICROTICA_PROJECT_ID="z2wti53si2xk61nehxds"

Or pass --project <id> to any command. The flag takes precedence over the environment variable and may appear before or after the subcommand:

microtica --project "$PROJECT_ID" env list
microtica env list --project "$PROJECT_ID"

Discover accessible IDs with microtica project list.

Output and global flags

Human-readable tables are the default for list commands. Use the global flags for scripts and agents:

| Flag | Behavior | | --- | --- | | --json | Write the raw result as formatted JSON. | | --query <expr> | Apply a JMESPath expression and emit JSON on standard data commands; implies machine-readable output. Log commands use it only to select NDJSON mode. | | --quiet | Suppress non-essential output. | | --project <id> | Select the project. |

Examples:

# Select only the fields the caller needs.
microtica env list --query '[].{id:id,name:name,status:status}'

# Produce newline-delimited values for a shell loop.
microtica pipeline list --query '[].id' | jq -r '.[]'

# Failed deployments across the project.
microtica pipeline history --type deploy \
  --query "pipelines[?status!='SUCCEEDED'].{id:id,env:envId,status:status}"

Errors are written to stderr and stdout stays clean. With --json, errors have this stable envelope:

{
  "error": {
    "kind": "api",
    "status": 400,
    "code": 400,
    "message": "Request could not be completed",
    "details": {}
  }
}

kind is api, validation, or local. API responses are open schemas: optional fields may be absent and new fields may appear.

Command map

Use microtica <group> --help and microtica <group> <command> --help for the complete flag reference installed with your version.

| Area | Commands | Purpose | | --- | --- | --- | | Identity | login, whoami | Store credentials and verify access. | | Projects | project list, project get | Discover and inspect projects. | | Environments | env list, get, get-details, get-resource | Inspect environments and their infrastructure resources. | | Environment deploys | env last-deploy, deploy, wait, clone, replicate | Query, trigger, wait for, clone, or fully replicate environments. | | Environment resources | env add-resource, update-resource, remove-resource | Change an environment specification and resource configuration. | | Environment cleanup | env undeploy, env delete | Tear down cloud resources, then remove the Microtica record. | | Apps | app list, get, status, last-deploy, logs | Inspect Kubernetes-deployed applications. | | App changes | app deploy, declare, update-config, resources, replicas | Deploy, configure, and scale apps. | | Git | git accounts list, repos list, branches list | Discover connected accounts, repositories, and branches. | | Pipelines | pipeline list, get, create, update, spec update, trigger, delete | Manage pipeline definitions and runs. | | History | pipeline history, pipeline builds list, pipeline builds get | Query correlated history or raw per-pipeline builds. | | Components | component list, get, create, init | Manage reusable infrastructure components. | | Logs | logs build, logs deploy, logs app | Read normalized pipeline, infrastructure, and app logs. | | Agents | agents, agents <topic>, agents --full | Print the version-matched agent reference. |

Common workflows

Inspect a project

microtica project list
export MICROTICA_PROJECT_ID="$(microtica project list --query '[0].id')"

microtica env list
microtica app list
microtica pipeline history --limit 20

env get returns top-level metadata. Use env get-details when actual resource configuration is required:

microtica env get-details "$ENV_ID" \
  --query 'resources[].{name:name,status:status,configurations:configurations}'
microtica env get-resource "$ENV_ID" RDS --json

Find the last deployment

Apps and environment resources use different deployment models:

# Kubernetes app: independent app deployment timeline.
microtica app last-deploy api --env "$ENV_ID" --json

# Infrastructure resource: latest environment run that targeted this resource.
microtica env last-deploy RDS --env "$ENV_ID" --json

An environment deployment is one run that may touch multiple resources. The env last-deploy result therefore exposes both environment-run status and the matching resource target's status and commit. Use targetStatus to reason about that resource, and pass its envDeployId to logs deploy.

Trigger and observe an environment deployment

DEPLOY_ID="$(microtica env deploy "$ENV_ID" --query deploymentId)"
microtica logs deploy "$ENV_ID" "$DEPLOY_ID" --follow --timeout 30m

For a subset of resources:

# Resolve the latest component build automatically.
microtica env deploy "$ENV_ID" --partial-resource Web

# Pin a build and combine it with a latest build.
microtica env deploy "$ENV_ID" \
  --partial-resource Web=4f3a9c21 \
  --partial-resource Api=latest

Partial Terraform deploys limit the apply set, not the plan: Microtica still plans the entire workspace. Plan-time failures elsewhere can therefore block a partial deploy.

Update environment resource configuration

env update-resource merges with the live configuration by default. This is important because the upstream update API replaces the entire set.

# resource-config.yaml
env: staging
domain_name: staging.example.com
InternalListenerArn:
  value: SharedIngress.InternalListenerArn
  reference: true

microtica env update-resource "$ENV_ID" Web \
  --config-file resource-config.yaml

Use --no-merge only when intentionally replacing every configuration entry. The API silently drops empty-string values; use a single space and trim it in the Terraform consumer if an explicit empty value is required.

Before adding a resource, inspect its version-specific schema:

microtica env add-resource "$ENV_ID" \
  --name Cache \
  --component redis-component \
  --version latest \
  --show-schema

microtica env add-resource "$ENV_ID" \
  --name Cache \
  --component redis-component \
  --set node_type=cache.t4g.small \
  --secret auth_token="$REDIS_TOKEN"

Scale an app safely

Use the scaling commands instead of building an app config file by hand. They read live state, preserve regular and sensitive configuration, validate bounds, and deploy the merged result.

# Show current settings.
microtica app resources api --env "$ENV_ID"
microtica app replicas api --env "$ENV_ID"

# Change settings.
microtica app resources api --env "$ENV_ID" \
  --cpu 1000m --memory 1Gi --memory-limit 2Gi
microtica app replicas api --env "$ENV_ID" --min 2 --max 6

When --cpu is set without --cpu-limit, the limit is set to the same value. Pass both to allow CPU bursting. If the app has multiple deployments, scope it with --env or pass both --cluster and --namespace.

Deploy an app

An image-only deploy preserves live configuration:

microtica app deploy api \
  --cluster "$CLUSTER_ID" \
  --namespace microtica \
  --image "$IMAGE_TAG"

Passing --config-file explicitly replaces the entire app environment-variable set. The file must be a top-level array—flat maps and { "configurations": [...] } wrappers are rejected:

[
  { "key": "DOMAIN_NAME", "value": "api.example.com" },
  { "key": "DB_PASSWORD", "value": "plain-secret", "sensitive": true }
]

For a sensitive entry, plaintext creates or updates the Kubernetes Secret. A secretName:KEY value with sensitive: true preserves an existing secret reference. Never omit the sensitive flag from a secret reference.

Query pipelines and components

Prefer combined history for project-wide questions:

microtica pipeline history --env "$ENV_ID" --type deploy --limit 100
microtica pipeline history --app api --limit 100
microtica pipeline history --resource RDS --include-events

Use pipeline builds list only for the raw history of one pipeline. Pipeline list/build-list responses omit large microticaYaml, schema, readme, and kube config fields by default; pass --full or fetch one record when needed.

Create and trigger a pipeline:

microtica pipeline create \
  --name infrastructure \
  --account "$GIT_ACCOUNT_ID" \
  --repo https://github.com/example/infrastructure \
  --automated-trigger \
  --branch-filter '^(main|develop)$'

microtica pipeline trigger "$PIPELINE_ID" --ref main --var TARGET_ENV=staging

component init orchestrates pipeline creation, component creation, and the initial build. It rolls back partial creation on failure unless --no-rollback is supplied.

Logs

All log groups share filtering and timeout flags:

microtica logs build "$PIPELINE_ID" "$BUILD_ID" --follow --timeout 20m
microtica logs deploy "$ENV_ID" "$DEPLOY_ID" --failures-only
microtica logs app api --env "$ENV_ID" --tail 200 --search 'error|panic' -i

Useful flags include --since, --until, --tail, --search, --grep-context, --failures-only, --follow, --timeout, and --no-truncate. Capabilities differ by source; unsupported combinations fail validation instead of silently doing something else. App logs are snapshot-only in this release.

With --json, logs are NDJSON: one normalized entry per line followed by an end marker. This makes streaming safe without buffering an entire JSON array.

{"timestamp":"2026-05-22T14:08:16.000Z","severity":"info","source":"pipeline","message":"building image"}
{"event":"end","sourceType":"build","status":"success","statusRaw":"SUCCEEDED","exitedAt":"2026-05-22T14:11:26.000Z","durationMs":190000}

Log commands use richer exit codes:

| Code | Meaning | | --- | --- | | 0 | Clean exit; observed success or no observable status. | | 1 | CLI, validation, authentication, network, or API error. | | 2 | Interrupted, disconnected, or timed out before clean completion. | | 3 | Clean observation of a failed or cancelled operation. |

All other commands use 0 for success and 1 for errors.

Destructive operations

Treat these as two separate actions:

1. microtica env undeploy <envId> destroys managed cloud resources but keeps the Microtica environment record.
2. microtica env delete <envId> removes the record. Deleting before undeploying can orphan cloud resources.

Both require typing the environment ID in an interactive terminal. Automation must pass --yes explicitly. env delete refuses a still-deployed environment; --force bypasses that check and should be reserved for a deliberate orphaning decision.

Removing a resource with env remove-resource only changes the environment specification. Deploy afterward to reconcile the cloud state.

Coding-agent contract

The CLI ships a version-matched, offline reference designed for language models:

microtica agents                 # compact index and topic list
microtica agents --list          # topic names only
microtica agents env             # one focused section
microtica agents logs
microtica agents --full          # complete reference; intentionally large

Recommended agent behavior:

• Start with microtica agents; fetch only the relevant topic to conserve context.
• Use --json for stable structure and --query for narrow projections on standard commands. Use log-specific filters for NDJSON log streams.
• Check the process exit code and stderr; do not infer success from stdout.
• Treat responses as open schemas and tolerate missing optional fields.
• Prefer app last-deploy or env last-deploy for one-target questions and pipeline history for cross-project timelines.
• Fetch details only when needed: env get-details, pipeline get, and pipeline builds get can be much larger than list responses.
• Never pass --yes, --force, --no-merge, or an app --config-file without understanding the state-changing semantics.

Troubleshooting

• Not logged in: set MICROTICA_TOKEN or run microtica login.
• Project ID required: pass --project or set MICROTICA_PROJECT_ID.
• Ambiguous app deployment: pass --env, or both --cluster and --namespace.
• Repository branch not found: pipeline trigger --ref accepts a branch name, refs/heads/..., or refs/tags/...; inspect branches with git branches list. The repository argument there is the full URL.
• Large pipeline output: omit --full and project only needed fields with --query.
• No app log follow: app pod logs are snapshot-only; use repeated snapshots or kubectl logs -f when direct cluster access is appropriate.
• Need exact output shapes: run microtica agents <topic> from the same installed CLI version.

Development

From the repository root:

npm install
npm run build --workspace @microtica/cli
npm test --workspace @microtica/cli
node cli/dist/bin/microtica.js --help

The CLI consumes @microtica/sdk. When command behavior or an output contract changes, update the root AGENTS.md in the same change; the build copies it into the published CLI.